Claude Git Branching

Claude Git Branching

Master Git workflows optimized for Claude Code development sessions with intelligent branching, retry logic, and automated PR creation.

Overview

This skill provides battle-tested Git workflows specifically designed for Claude Code sessions, including:

• Claude-specific branch naming conventions
• Automatic push retry with exponential backoff
• Multi-repository coordination
• Conflict-free collaboration patterns
• Automated PR creation and management

When to Use

Use this skill when:

• Starting a new Claude Code development session
• Managing multiple feature branches across sessions
• Dealing with intermittent network issues during push
• Creating PRs from Claude-generated code
• Coordinating work across multiple repositories
• Following team Git conventions for AI-assisted development
• Handling merge conflicts in long-running sessions

Branch Naming Conventions

Claude Code Standard Format

# Standard format
claude/[feature-name]-[session-id]

# Examples
claude/harvest-claude-skills-01MtCwKhDQhWyZCgwfkhdVG5
claude/fix-auth-bug-01NAB2cDE3FgHiJ4KlM5NoPq
claude/add-api-endpoints-01PQRsT6UvWxY7ZaBcD8EfGh

Format requirements:

• Prefix: Must start with claude/
• Feature name: Kebab-case description of work
• Session ID: Unique identifier for the session
• Maximum length: 100 characters recommended

Why this format?

• ✅ Clear AI-assisted development marker
• ✅ Prevents conflicts with human developer branches
• ✅ Traceable to specific session
• ✅ Easy to filter and manage
• ✅ Works with GitHub access controls (required for push)

Alternative Formats

# Team-based
claude/[team]/[feature]-[session-id]
claude/backend/api-optimization-01ABC

# Priority-based
claude/[priority]/[feature]-[session-id]
claude/urgent/security-patch-01DEF

# Issue-based
claude/issue-[number]-[session-id]
claude/issue-1234-01GHI

Branch Creation Workflow

Step 1: Check Current State

# Verify current branch
git branch --show-current

# Check status
git status

# View recent branches
git branch -a | grep "claude/" | head -10

Step 2: Create Feature Branch

# From main/master
git checkout main
git pull origin main

# Create Claude branch
FEATURE="add-user-authentication"
SESSION_ID="01MtCwKhDQhWyZCgwfkhdVG5"
BRANCH="claude/${FEATURE}-${SESSION_ID}"

git checkout -b "$BRANCH"
echo "Created branch: $BRANCH"

Step 3: Verify Branch Name

# Ensure proper format
CURRENT_BRANCH=$(git branch --show-current)

if [[ ! "$CURRENT_BRANCH" =~ ^claude/.+-[0-9A-Za-z]{20,}$ ]]; then
    echo "⚠️  Warning: Branch name doesn't match Claude format"
    echo "Expected: claude/[feature-name]-[session-id]"
    echo "Got: $CURRENT_BRANCH"
fi

Push with Retry Logic

Standard Push Pattern

#!/bin/bash
# push-with-retry.sh - Push with exponential backoff

BRANCH=$(git branch --show-current)
MAX_RETRIES=4
RETRY_COUNT=0
DELAYS=(2 4 8 16)  # Exponential backoff in seconds

echo "Pushing branch: $BRANCH"

while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
    if git push -u origin "$BRANCH"; then
        echo "✓ Successfully pushed to origin/$BRANCH"
        exit 0
    else
        EXIT_CODE=$?
        RETRY_COUNT=$((RETRY_COUNT + 1))

        # Check if it's a 403 error (branch name issue)
        if git push -u origin "$BRANCH" 2>&1 | grep -q "403"; then
            echo "✗ Push failed with 403 - Check branch naming convention"
            echo "Branch must start with 'claude/' and end with session ID"
            exit 1
        fi

        if [ $RETRY_COUNT -lt $MAX_RETRIES ]; then
            DELAY=${DELAYS[$RETRY_COUNT-1]}
            echo "⚠️  Push failed (attempt $RETRY_COUNT/$MAX_RETRIES)"
            echo "Retrying in ${DELAY}s..."
            sleep $DELAY
        fi
    fi
done

echo "✗ Push failed after $MAX_RETRIES attempts"
exit 1

Usage:

chmod +x push-with-retry.sh
./push-with-retry.sh

Inline Retry Pattern

# Quick inline version
for i in {1..4}; do
    if git push -u origin $(git branch --show-current); then
        echo "✓ Pushed successfully"
        break
    else
        [ $i -lt 4 ] && echo "Retry $i/4..." && sleep $((2**i))
    fi
done

Commit Best Practices

Atomic Commits

# Make focused, atomic commits
git add src/auth/login.ts
git commit -m "feat: Add JWT-based login authentication"

git add src/auth/middleware.ts
git commit -m "feat: Add auth middleware for protected routes"

git add tests/auth.test.ts
git commit -m "test: Add authentication test suite"

Commit Message Format

# Format: : 
# Types: feat, fix, docs, refactor, test, chore, style, perf

git commit -m "$(cat &1 | grep -v "up-to-date" || true

# Create PR
echo ""
echo "Creating pull request..."
gh pr create \
    --base "$BASE_BRANCH" \
    --head "$BRANCH" \
    --title "$TITLE" \
    --body "$PR_BODY"

if [ $? -eq 0 ]; then
    echo "✓ PR created successfully"
    gh pr view --web
else
    echo "✗ Failed to create PR"
    exit 1
fi

PR Templates

## Description

## Type of Change
- [ ] 🎯 New feature
- [ ] 🐛 Bug fix
- [ ] 📚 Documentation update
- [ ] ♻️ Refactoring
- [ ] ⚡ Performance improvement
- [ ] ✅ Test addition/update

## Claude Code Session
- **Branch**: `[branch-name]`
- **Session ID**: `[session-id]`
- **Duration**: `[time spent]`

## Changes Made
- Change 1
- Change 2
- Change 3

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing completed
- [ ] No regressions identified

## Checklist
- [ ] Code follows project style guide
- [ ] Self-review completed
- [ ] Comments added for complex logic
- [ ] Documentation updated
- [ ] No new warnings introduced

## Screenshots (if applicable)

## Related Issues

Multi-Repository Management

Coordinating Across Repos

#!/bin/bash
# sync-multi-repo.sh - Sync work across multiple repositories

REPOS=(
    "/path/to/frontend"
    "/path/to/backend"
    "/path/to/shared-lib"
)

BRANCH_PREFIX="claude/sync-auth-update"
SESSION_ID="01MtCwKhDQhWyZCgwfkhdVG5"

for REPO in "${REPOS[@]}"; do
    echo "=== Processing: $REPO ==="
    cd "$REPO" || continue

    REPO_NAME=$(basename "$REPO")
    BRANCH="${BRANCH_PREFIX}-${REPO_NAME}-${SESSION_ID}"

    # Create branch
    git checkout -b "$BRANCH" 2>/dev/null || git checkout "$BRANCH"

    echo "Ready for changes in: $BRANCH"
    echo ""
done

Batch Commit and Push

#!/bin/bash
# commit-multi-repo.sh - Commit across multiple repos

REPOS=("frontend" "backend" "shared-lib")
COMMIT_MSG="$1"

if [ -z "$COMMIT_MSG" ]; then
    echo "Usage: $0 "
    exit 1
fi

for REPO in "${REPOS[@]}"; do
    echo "=== $REPO ==="
    cd "$REPO" || continue

    # Check if there are changes
    if [ -n "$(git status --porcelain)" ]; then
        git add .
        git commit -m "$COMMIT_MSG"

        # Push with retry
        for i in {1..4}; do
            if git push -u origin $(git branch --show-current); then
                echo "✓ Pushed $REPO"
                break
            else
                [ $i -lt 4 ] && sleep $((2**i))
            fi
        done
    else
        echo "No changes in $REPO"
    fi

    cd - > /dev/null
    echo ""
done

Conflict Resolution

Pre-merge Conflict Detection

# Before merging, check for conflicts
git fetch origin main
git merge-base origin/main HEAD
git diff origin/main...HEAD --name-only

# Test merge without committing
git merge --no-commit --no-ff origin/main

# If conflicts, abort and review
git merge --abort

Conflict Resolution Workflow

#!/bin/bash
# resolve-conflicts.sh

# Update main
git fetch origin main

# Attempt merge
if git merge origin/main; then
    echo "✓ Merged cleanly"
else
    echo "⚠️  Conflicts detected"

    # Show conflicts
    git diff --name-only --diff-filter=U

    # For each conflict
    git status | grep "both modified" | awk '{print $3}' | while read file; do
        echo ""
        echo "=== Conflict in: $file ==="

        # Show conflict markers
        grep -n "> .git/config << EOF

[branch "claude/*"]
    # Auto-setup upstream
    autoSetupMerge = always

[remote "origin"]
    # Fetch all claude branches
    fetch = +refs/heads/claude/*:refs/remotes/origin/claude/*
EOF

Troubleshooting

Issue 1: 403 Error on Push

Symptoms:

error: failed to push some refs to 'https://github.com/user/repo.git'
! [remote rejected] claude/feature-abc123 (permission denied)

Cause: Branch name doesn't match required claude/*-[session-id] format

Solution:

# Check current branch name
CURRENT=$(git branch --show-current)
echo "Current: $CURRENT"

# Rename if needed
SESSION_ID="01MtCwKhDQhWyZCgwfkhdVG5"
NEW_BRANCH="claude/feature-name-${SESSION_ID}"
git branch -m "$CURRENT" "$NEW_BRANCH"

# Push with new name
git push -u origin "$NEW_BRANCH"

Issue 2: Network Timeout During Push

Symptoms:

fatal: the remote end hung up unexpectedly
error: failed to push some refs

Cause: Intermittent network issues

Solution: Use retry logic (see "Push with Retry Logic" section)

Issue 3: Divergent Branches

Symptoms:

hint: You have divergent branches and need to specify how to reconcile them.

Cause: Local and remote branches have different histories

Solution:

# Option 1: Rebase (cleaner history)
git pull --rebase origin $(git branch --show-current)

# Option 2: Merge (preserves all history)
git pull --no-rebase origin $(git branch --show-current)

# Option 3: Reset to remote (discard local changes)
git reset --hard origin/$(git branch --show-current)

Best Practices

✅ DO

1. Always use claude/ prefix for session branches
2. Include session ID in branch name
3. Push with retry logic for network resilience
4. Create atomic commits with clear messages
5. Rebase before PR to clean up history
6. Test before pushing to avoid broken builds
7. Use conventional commits for clear history
8. Clean up merged branches regularly

❌ DON'T

1. Don't commit secrets or credentials
2. Don't force push to main/master
3. Don't create generic branch names without session ID
4. Don't skip commit messages or use placeholders
5. Don't leave unresolved conflicts in commits
6. Don't commit large binary files without LFS
7. Don't bypass CI checks without good reason
8. Don't mix unrelated changes in single commit

Quick Reference

Common Commands

# Create Claude branch
git checkout -b claude/feature-name-$(date +%s)

# Push with retry
for i in {1..4}; do git push -u origin $(git branch --show-current) && break || sleep $((2**i)); done

# Create PR
gh pr create --title "feat: Description" --body "Details here"

# Clean merged branches
git branch --merged main | grep "claude/" | xargs git branch -d

# Show branch stats
git log main..HEAD --oneline --stat

# Squash last 3 commits
git rebase -i HEAD~3

Workflow Cheat Sheet

1. Start: git checkout -b claude/[feature]-[session-id]
2. Work: Make changes, commit atomically
3. Push: git push -u origin $(git branch --show-current) (with retry)
4. PR: gh pr create or use GitHub UI
5. Merge: Squash and merge through GitHub
6. Clean: git branch -d claude/[feature]-[session-id]

---

Version: 1.0.0 Author: Harvested from yourclaudeskills repository Last Updated: 2025-11-18 License: MIT

Integration with Claude Code

This skill integrates seamlessly with Claude Code workflows:

• Automatically suggests branch names during session start
• Provides retry logic for unreliable networks
• Generates PR descriptions from commit history
• Handles multi-repo coordination
• Manages cleanup of old branches

Use this skill at the start of every Claude Code session for optimal Git workflow management! 🚀

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jackspace
• Source: jackspace/ClaudeSkillz
• License: MIT
• Homepage: http://claudeskillz.jackspace.com/

Install and usage instructions live in the source repository linked above.