Easy Branch Executor

Create, switch, and manage Git branches with automated naming conventions and upstream tracking.

When to Use This Command

Run this command when you need to:

• Create a new feature, bugfix, or hotfix branch following team naming conventions
• Switch between branches with automatic stash and restore of uncommitted changes
• Clean up merged branches and synchronize local branches with the remote

Consider alternatives when:

• You need a simple git checkout and know the exact branch name
• You are working with Git worktrees and need isolated working directories instead of branch switching

Quick Start

Configuration

Copy
name: easy-branch-executor
type: command
category: git-workflow

Example Invocation

Copy
claude command:run easy-branch-executor --action create --type feature --name user-auth

Example Output

Branch Operation: create
Convention: feature/user-auth
Base Branch: main (up to date with origin/main)

Pre-flight:
  [OK] Working tree is clean
  [OK] Base branch is up to date with remote
  [OK] No existing branch named feature/user-auth

Execution:
  [+] Fetched latest from origin
  [+] Created branch: feature/user-auth (from main @ a1b2c3d)
  [+] Set upstream tracking: origin/feature/user-auth
  [+] Switched to feature/user-auth

Current state:
  Branch: feature/user-auth
  Base commit: a1b2c3d (main: "Update dependencies")
  Tracking: origin/feature/user-auth (will be created on first push)

Core Concepts

Branch Management Overview

Aspect	Details
Naming Convention	Enforces type/name format: feature/, bugfix/, hotfix/, release/
Base Branch Logic	Features branch from main, hotfixes from the latest release tag
Stash Management	Automatically stashes uncommitted changes when switching branches
Upstream Tracking	Configures remote tracking branch for push/pull operations
Cleanup	Removes merged branches locally and optionally from the remote

Branch Workflow

  Branch Request
       |
       v
  +-------------------+
  | Validate Naming   |---> Enforce type/name convention
  +-------------------+
       |
       v
  +-------------------+
  | Determine Base    |---> main, develop, or release tag
  +-------------------+
       |
       v
  +-------------------+
  | Stash if Needed   |---> Save uncommitted work
  +-------------------+
       |
       v
  +-------------------+
  | Create / Switch   |---> git checkout -b or git switch
  +-------------------+
       |
       v
  +-------------------+
  | Set Upstream       |---> Configure remote tracking
  +-------------------+

Configuration

Parameter	Type	Default	Description
action	string	create	Branch action: create, switch, delete, cleanup, list
type	string	feature	Branch type prefix: feature, bugfix, hotfix, release, chore
name	string	required	Descriptive branch name (will be kebab-cased automatically)
base	string	main	Base branch or tag to branch from
push	boolean	false	Push the new branch to remote immediately after creation

Best Practices

1. Use Consistent Branch Type Prefixes - Enforce feature/, bugfix/, hotfix/ prefixes across the team. Consistent prefixes enable CI/CD rules (e.g., only hotfix/ branches trigger expedited pipelines) and make branch purpose obvious at a glance.

2. Always Branch From an Updated Base - Fetch the latest remote state before creating a branch. Branching from a stale local main creates unnecessary merge conflicts when the work is complete.

3. Delete Branches After Merging - Merged branches clutter the branch list and make it difficult to find active work. Configure automatic branch deletion on merge in your Git hosting platform.

4. Stash Before Switching - Uncommitted changes can conflict with the target branch or accidentally end up in the wrong branch. Automatic stashing before switch and restoring after switch prevents this class of errors.

5. Keep Branch Names Short but Descriptive - Branch names like feature/user-auth are ideal. Avoid long names like feature/implement-oauth2-authentication-with-google-and-github-providers that are difficult to type and truncated in most tools.

Common Issues

1. Branch Name Already Exists - A branch with the same name exists locally or on the remote. Check for existing branches before creating and suggest an alternative name or offer to switch to the existing branch.

2. Stash Conflicts on Restore - Stashed changes conflict with the target branch after switching. Pop the stash with --index to preserve staging state, and if conflicts occur, leave the stash intact so the developer can resolve manually.

3. Upstream Tracking Not Set - Pushing fails because no upstream branch is configured. Use git push -u origin branch-name on the first push to establish tracking, or set it automatically during branch creation.