git-branch-manager

When to Invoke This Skill

• Creating a new feature/fix/chore branch
• Switching between branches
• Cleaning up merged branches
• Handling uncommitted changes before branch operations
• Validating current branch state

Core Capabilities

1. Branch Creation - Create properly named branches from main
2. Branch Switching - Safe branch changes with uncommitted change handling
3. Branch Cleanup - Remove local branches after merge
4. Branch Validation - Verify branch state and history

Standard Workflows

#### Creating a New Branch

1. Check Repository State

Invoke the git-state-validator skill to verify:

- Current branch status

- Uncommitted changes

- Working directory state

1. Handle Uncommitted Changes

If changes exist, ask user:

- Stash: git stash push -m "WIP: switching to new branch"

- Commit: Guide through commit process first

- Abort: Cancel branch creation

1. Ensure Latest Main

```bash

git checkout main

git fetch origin

git pull origin main

```

1. Determine Branch Prefix

Based on work type:

- feat/ - New features

- fix/ - Bug fixes

- chore/ - Maintenance, tooling

- docs/ - Documentation

- refactor/ - Code refactoring

- test/ - Test additions/fixes

- perf/ - Performance improvements

1. Create Branch

```bash

git checkout -b /

```

Branch name format:

- Use kebab-case

- Maximum 50 characters

- Descriptive but concise

- Example: feat/add-user-authentication

#### Switching Branches

1. Check Repository State

Invoke the git-state-validator skill to verify:

- Current branch name

- Uncommitted changes

- Working directory status

1. Handle Changes (if any)

- Offer to stash, commit, or abort

- If stash: git stash push -m "WIP: switching from to "

1. Switch Branch

```bash

git checkout

```

1. Restore Stash (if applicable)

After switching, if user stashed:

```bash

git stash list

git stash pop

```

#### Cleaning Up Branches

1. Verify Branch is Merged

```bash

git branch --merged main

```

1. Switch to Main (if on the branch being deleted)

```bash

git checkout main

```

1. Check Branch Exists Before Deletion

```bash

git branch --list

```

If no output, branch doesn't exist - skip deletion

1. Delete Local Branch (only if exists)

```bash

git branch -d

```

Use -D (force delete) only if user explicitly confirms:

```bash

git branch -D

```

1. Verify Deletion

```bash

git branch --list

```

Safe Branch Deletion Helper

CRITICAL: Always check if branch exists before attempting deletion to avoid errors.

Safe Deletion Pattern:

```bash

# Check if branch exists

if git branch --list | grep -q ; then

git branch -d

echo "Branch deleted"

else

echo "Branch does not exist, skipping"

fi

```

Why This Matters:

• Prevents "branch not found" errors in automated workflows
• Handles cases where remote deletion already removed local tracking branch
• Makes cleanup scripts idempotent (safe to run multiple times)

Branch Naming Conventions

Good Examples:

• feat/user-profile-page
• fix/login-validation-error
• chore/update-dependencies
• docs/api-endpoint-guide

Bad Examples:

• my-branch (no type prefix)
• feat/ThisIsMyNewFeature (not kebab-case)
• feat/add-the-new-user-profile-page-with-authentication-and-settings (too long)

Error Handling

Branch Already Exists:

Ask user to:

• Switch to existing: git checkout
• Delete and recreate: git branch -D && git checkout -b
• Choose different name

Uncommitted Changes Conflict:

```

error: Your local changes to the following files would be overwritten by checkout

```

• Must stash or commit changes first
• Cannot proceed without handling changes

Merge Conflicts When Pulling:

```

error: Merge conflict in

```

• Must resolve conflicts before creating branch
• Guide user through conflict resolution

Cannot Delete Current Branch:

```

error: Cannot delete branch '' checked out at ''

```

• Must switch to different branch first
• Run: git checkout main then retry delete

Example 1: Create feature branch for issue

```

Context: Working on issue #42 to add dark mode

Action:

1. Check uncommitted changes (none found)
2. Switch to main: git checkout main
3. Update main: git pull origin main
4. Create branch: git checkout -b feat/add-dark-mode-toggle

Output: "Created and switched to feat/add-dark-mode-toggle"

```

Example 2: Switch branches with uncommitted work

```

Context: User has uncommitted changes, wants to switch branches

Action:

1. Detect uncommitted changes
2. Ask user: "You have uncommitted changes. Stash, commit, or abort?"
3. User chooses stash
4. Run: git stash push -m "WIP: switching branches"
5. Switch: git checkout other-branch
6. Offer to pop stash if returning later

```

Example 3: Clean up after merge

```

Context: PR merged, need to clean up local branch

Action:

1. Verify branch is merged: git branch --merged main
2. Switch to main: git checkout main
3. Check if branch exists: git branch --list feat/old-feature
4. Delete branch (if exists): git branch -d feat/old-feature
5. Update main: git pull origin main

Output: "Branch cleaned up, main is up to date"

```

Example 4: Handle branch naming

```

Context: User wants to fix a bug in login validation

Action:

1. Determine type: "fix" (bug fix)
2. Extract description: "login validation"
3. Format: fix/login-validation-error
4. Create: git checkout -b fix/login-validation-error

```