git-branch-manager

name	git-branch-manager
description	Create, switch, and manage git branches with proper handling of uncommitted changes. Use when creating feature branches, switching contexts, or cleaning up after merges.

Git Branch Manager

Instructions

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

2. 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

3. Ensure Latest Main

   git checkout main
   git fetch origin
   git pull origin main
   

4. 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

5. Create Branch

   git checkout -b <prefix>/<description>
   

   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

2. Handle Changes (if any)

   • Offer to stash, commit, or abort
   • If stash: git stash push -m "WIP: switching from <current> to <target>"

3. Switch Branch

   git checkout <branch-name>
   

4. Restore Stash (if applicable) After switching, if user stashed:

   git stash list
   git stash pop
   

Cleaning Up Branches

1. Verify Branch is Merged

   git branch --merged main
   

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

   git checkout main
   

3. Check Branch Exists Before Deletion

   git branch --list <branch-name>
   

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

4. Delete Local Branch (only if exists)

   git branch -d <branch-name>
   

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

   git branch -D <branch-name>
   

5. Verify Deletion

   git branch --list <branch-name>
   

Safe Branch Deletion Helper

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

Safe Deletion Pattern:

# Check if branch exists
if git branch --list <branch-name> | grep -q <branch-name>; then
  git branch -d <branch-name>
  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 <branch-name>
• Delete and recreate: git branch -D <branch-name> && git checkout -b <branch-name>
• 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 <file>

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

Cannot Delete Current Branch:

error: Cannot delete branch '<name>' checked out at '<path>'

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

Examples

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