Skip to content
LiveNew tools this week
Submit
AIMarketly
git.branch.manage logo

git.branch.manage

Create, checkout, rebase, and manage git branches following Carbon ACX naming conventions and workflows.

mattnigh/skills_collection0installs24stars

SKILL.md

Full skill instructions

git.branch.manage

Purpose

This skill automates git branch management for Carbon ACX by:

  • Creating branches with proper naming conventions
  • Checking out existing branches safely
  • Managing branch state (tracking, upstream)
  • Performing rebases and merges
  • Detecting and reporting merge conflicts
  • Cleaning up stale branches
  • Ensuring proper branch hygiene

When to Use

Trigger Patterns:

  • "Create a branch for..."
  • "Switch to branch..."
  • "Rebase this branch"
  • "Update my branch from main"
  • "Delete old branches"
  • Before starting new work on a feature/​fix

Do NOT Use When:

  • Making commits (use git.commit.smart)
  • Creating PRs (use git.pr.create)
  • Resolving complex merge conflicts (requires human judgment)

Allowed Tools

  • bash - Git commands
  • grep - Search branch lists, commit messages

Access Level: 2 (Git operations - can create/​delete branches)

Tool Rationale:

  • bash: Required for all git branch operations
  • grep: Filter branch lists and search patterns

Explicitly Denied:

  • No force deleting branches without confirmation
  • No rebasing published branches without warning
  • No modifying main/​master branches

Expected I/​O

Input:

  • Type: Branch management request
  • Context: Current working state, branch name/​description
  • Optional: Base branch (defaults to main/​master)

Example:

"Create a feature branch for dark mode"
"Switch to the UX improvements branch"
"Rebase my branch on main"
"Delete merged branches"

Output:

  • Type: Branch operation completed
  • Format: Confirmation message with branch state
  • Includes:
    • Branch name used
    • Operation performed (create, checkout, rebase, delete)
    • Current HEAD position
    • Any conflicts or warnings

Validation:

  • Branch name follows conventions
  • No uncommitted changes (or properly handled)
  • Operations succeed without data loss
  • User informed of branch state changes

Dependencies

Required:

  • Git repository
  • Clean working directory (or stashing strategy)

Optional:

  • Remote repository configured for push/​pull operations

Workflow

Branch Creation

Step 1: Determine Branch Name

Naming Convention:

<type>/<description>

Types:

  • feat/ or feature/ - New features
  • fix/ or bugfix/ - Bug fixes
  • chore/ - Maintenance, tooling, dependencies
  • docs/ - Documentation only
  • refactor/ - Code restructuring
  • test/ - Test additions/​updates
  • perf/ - Performance improvements

Description:

  • Lowercase with hyphens (kebab-case)
  • Concise but descriptive (3-5 words)
  • No special characters except hyphens

Examples:

  • feat/​dark-mode-toggle
  • fix/​aviation-calculation-error
  • chore/​update-react-dependencies
  • docs/​update-api-documentation
  • refactor/​component-structure

Alternative naming (also accepted):

  • feature/​description
  • bugfix/​description
  • User-specified names (if they follow convention)
Step 2: Check for Existing Branch
git branch --list "feat/​dark-mode-toggle"
git branch -r --list "*/​feat/​dark-mode-toggle"

If exists: Ask user if they want to:

  • Checkout existing branch
  • Create with different name
  • Delete and recreate (dangerous!)
Step 3: Determine Base Branch
# Check if main exists
git rev-parse --verify main 2>/​dev/​null

# Otherwise check for master
git rev-parse --verify master 2>/​dev/​null

Default: main (or master if main doesn't exist) User can override: "Create branch from develop"

Step 4: Fetch Latest
git fetch origin

Ensures base branch is up-to-date

Step 5: Create and Checkout
git checkout -b feat/​dark-mode-toggle origin/​main

Alternative (two-step):

git branch feat/​dark-mode-toggle origin/​main
git checkout feat/​dark-mode-toggle
Step 6: Confirm
git status
git log -1 --oneline

Report to user:

✅ Branch created: feat/​dark-mode-toggle
Base: origin/​main (abc1234)
Current HEAD: abc1234 chore: prepare release v1.3.0
Status: No commits yet, ready for work

Branch Checkout

Step 1: Check Working Directory
git status --porcelain

If uncommitted changes:

  • Offer to stash: git stash push -m "WIP: auto-stashed by git.branch.manage"
  • Or require commit first
Step 2: Find Branch

Local branches:

git branch --list "*pattern*"

Remote branches:

git branch -r --list "origin/​*pattern*"

If multiple matches: Present list to user for selection

If no matches: Suggest creating new branch

Step 3: Checkout

Local branch:

git checkout feat/​dark-mode-toggle

Remote branch (first checkout):

git checkout -b feat/​dark-mode-toggle origin/​feat/​dark-mode-toggle
Step 4: Confirm
git status

Report:

✅ Switched to branch: feat/​dark-mode-toggle
Tracking: origin/​feat/​dark-mode-toggle
Status: Up to date with remote

Branch Rebase

Step 1: Verify Current Branch
git rev-parse --abbrev-ref HEAD

Safety check: Never rebase main/​master directly

Step 2: Check Uncommitted Changes
git status --porcelain

If uncommitted: Require commit or stash first

Step 3: Fetch Latest
git fetch origin
Step 4: Rebase
git rebase origin/​main

If conflicts:

⚠️ Rebase conflict detected

Conflicting files:
- apps/​carbon-acx-web/​src/​components/​Dashboard.tsx
- package.json

Options:
1. Resolve conflicts manually
2. Abort rebase: git rebase --abort

To continue after resolving:
- git add <resolved-files>
- git rebase --continue

Do NOT auto-resolve conflicts - require human judgment

Step 5: If Successful
git log --oneline -5

Report:

✅ Rebase successful

Your branch has been rebased on origin/​main
Previous HEAD: abc1234
New HEAD: xyz9876

Commits on this branch: 3
- feat(web): add dark mode state management
- feat(web): create theme toggle component
- test(web): add theme switching tests

⚠️ Note: Branch history has been rewritten
If already pushed, you'll need to force-push: git push --force-with-lease

Branch Cleanup

Step 1: List Merged Branches
# Local branches merged to main
git branch --merged main | grep -v "main\|master\|\*"

# Remote merged branches
git branch -r --merged main | grep -v "main\|master"
Step 2: Present List

Show user:

Merged branches (safe to delete):
Local:
- feat/​dark-mode-toggle
- fix/​aviation-calculation

Remote:
- origin/​chore/​update-dependencies

Delete these branches? (yes/​no)
Step 3: Delete (if approved)

Local:

git branch -d feat/​dark-mode-toggle

Remote:

git push origin --delete feat/​dark-mode-toggle

Report:

✅ Deleted 2 local branches
✅ Deleted 1 remote branch

Remaining branches: 5

Examples

Example 1: Create Feature Branch

User: "Create a branch for dark mode feature"

Claude Process:

  1. Parse intent: Feature branch
  2. Generate name: feat/​dark-mode-toggle
  3. Check if exists: No
  4. Fetch origin
  5. Create from origin/​main: 
    git fetch origin
git checkout -b feat/​dark-mode-toggle origin/​main
  6. Report: 
    ✅ Created branch: feat/​dark-mode-toggle
Base: origin/​main (abc1234)
Ready to start work on dark mode feature

Example 2: Switch to Existing Branch

User: "Switch to the UX improvements branch"

Claude Process:

  1. Search branches: git branch --list "*ux*"
  2. Find match: feat/​ux-improvements
  3. Check working directory: Clean ✅
  4. Checkout: 
    git checkout feat/​ux-improvements
  5. Report: 
    ✅ Switched to: feat/​ux-improvements
Last commit: d4e5f6g refactor(web): improve dashboard layout
Status: 2 commits ahead of origin/​main

Example 3: Rebase on Main

User: "Rebase my branch on main"

Claude Process:

  1. Current branch: feat/​dark-mode-toggle
  2. Check uncommitted: Clean ✅
  3. Fetch: git fetch origin
  4. Rebase: 
    git rebase origin/​main
  5. Success: 
    ✅ Rebase successful
Your branch is now up-to-date with origin/​main
3 commits rebased
  6. Warn about force-push if already pushed

Example 4: Handle Rebase Conflict

User: "Update my branch from main"

Claude Process:

  1. Current branch: feat/​emission-chart
  2. Rebase: git rebase origin/​main
  3. Conflict detected: 
    ⚠️ Rebase stopped due to conflicts

Conflicting files:
- apps/​carbon-acx-web/​src/​components/​Chart.tsx
  (both modified)

Conflict type: Content conflict
Your changes: Added EmissionChart component
Main changes: Refactored base Chart component

Resolution needed:
1. Open Chart.tsx and resolve conflict markers
2. Keep both changes if compatible
3. After fixing:
   git add Chart.tsx
   git rebase --continue

To abort: git rebase --abort
  4. Wait for user to resolve
  5. Do NOT auto-resolve

Example 5: Clean Up Merged Branches

User: "Delete old branches"

Claude Process:

  1. List merged: 
    git branch --merged main
  2. Found: feat/​dark-mode-toggle, fix/​typo-readme
  3. Present list: 
    Merged branches (safe to delete):
- feat/​dark-mode-toggle (merged in PR #42)
- fix/​typo-readme (merged in PR #38)

Delete these? (yes/​no)
  4. User confirms: yes
  5. Delete: 
    git branch -d feat/​dark-mode-toggle fix/​typo-readme
  6. Report: 
    ✅ Deleted 2 local branches
Remaining: 3 active branches

Example 6: Create Branch from Specific Base

User: "Create a hotfix branch from v1.2.3 tag"

Claude Process:

  1. Parse: Hotfix, base is tag v1.2.3
  2. Verify tag exists: git rev-parse v1.2.3
  3. Generate name: hotfix/​urgent-security-fix (ask user for description)
  4. Create: 
    git checkout -b hotfix/​urgent-security-fix v1.2.3
  5. Report: 
    ✅ Created branch: hotfix/​urgent-security-fix
Base: v1.2.3 (tag)
⚠️ This branch is behind main - use for hotfix only

Limitations

Scope Limitations:

  • Cannot auto-resolve merge conflicts (requires human judgment)
  • Cannot rebase published/​shared branches without warning
  • Cannot delete branches with unmerged changes (safety)
  • Cannot modify protected branches (main/​master)

Known Edge Cases:

  • Detached HEAD state → Warn user, suggest creating branch from current state
  • Diverged branches (force-push needed) → Warn about risks
  • Stale remote branches → Suggest pruning with git remote prune
  • Branch name conflicts → Suggest alternative names

Performance Constraints:

  • Rebasing many commits (100+) may take time
  • Fetching from slow remotes may delay operations
  • Large conflicts difficult to present in text format

Security Boundaries:

  • Does not force-delete branches without confirmation
  • Does not auto-resolve conflicts (data loss risk)
  • Does not push to protected branches
  • Respects repository permissions

Validation Criteria

Success Metrics:

  • ✅ Branch names follow conventions
  • ✅ Operations complete without data loss
  • ✅ User informed of branch state changes
  • ✅ Conflicts detected and reported (not auto-resolved)
  • ✅ Working directory state preserved (stash if needed)
  • ✅ Remote tracking configured when appropriate

Failure Modes:

  • ❌ Uncommitted changes → Suggest commit or stash
  • ❌ Branch name invalid → Suggest corrected name
  • ❌ Merge conflict → Report, provide resolution steps
  • ❌ Remote unreachable → Suggest checking network
  • ❌ Branch doesn't exist → Suggest creating or list similar names

Recovery:

  • If conflict during rebase: Provide clear resolution steps
  • If branch exists: Offer alternatives (checkout, rename, delete)
  • If uncommitted changes: Offer stash or commit options
  • If operation fails: Provide git status and suggest next action

Related Skills

Composes With:

  • git.commit.smart - Commit work before switching branches
  • git.pr.create - Create PR after branch work complete
  • git.release.prep - Create release branch

Dependencies:

  • None - foundational skill

Alternative Skills:

  • For commits: git.commit.smart
  • For PRs: git.pr.create

Maintenance

Owner: Workspace Team (shared skill) Review Cycle: Quarterly Last Updated: 2025-10-24 Version: 1.0.0

Maintenance Notes:

  • Update branch naming conventions if Carbon ACX changes standards
  • Review rebase strategies as git workflows evolve
  • Adjust conflict detection logic for better reporting
  • Keep stash/​unstash behavior synchronized with user preferences