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: <type>: <description>
# Types: feat, fix, docs, refactor, test, chore, style, perf

git commit -m "$(cat <<'EOF'
feat: Add user authentication system

- Implement JWT-based authentication
- Add login/logout endpoints
- Create auth middleware
- Add session management

Closes #123
EOF
)"

Conventional Commits

# Feature
git commit -m "feat(auth): Add JWT authentication"

# Bug fix
git commit -m "fix(api): Handle null user in middleware"

# Documentation
git commit -m "docs(readme): Update authentication setup"

# Refactoring
git commit -m "refactor(auth): Extract token validation logic"

# Breaking change
git commit -m "feat(api)!: Change auth response format

BREAKING CHANGE: Auth response now returns user object instead of ID"

Pull Request Creation

Automated PR Creation

#!/bin/bash
# create-pr.sh - Create PR with gh CLI

BRANCH=$(git branch --show-current)
BASE_BRANCH="${1:-main}"

# Ensure we're on a Claude branch
if [[ ! "$BRANCH" =~ ^claude/ ]]; then
    echo "⚠️  Warning: Not on a Claude branch"
    read -p "Continue anyway? (y/n) " -n 1 -r
    echo
    [[ ! $REPLY =~ ^[Yy]$ ]] && exit 1
fi

# Get commit history since divergence
COMMITS=$(git log ${BASE_BRANCH}...HEAD --oneline)
DIFF_STAT=$(git diff ${BASE_BRANCH}...HEAD --stat)

# Analyze changes
FILES_CHANGED=$(git diff ${BASE_BRANCH}...HEAD --name-only | wc -l)
LINES_ADDED=$(git diff ${BASE_BRANCH}...HEAD --numstat | awk '{sum+=$1} END {print sum}')
LINES_REMOVED=$(git diff ${BASE_BRANCH}...HEAD --numstat | awk '{sum+=$2} END {print sum}')

echo "=== PR Summary ==="
echo "Branch: $BRANCH"
echo "Base: $BASE_BRANCH"
echo "Files changed: $FILES_CHANGED"
echo "Lines added: $LINES_ADDED"
echo "Lines removed: $LINES_REMOVED"
echo ""

# Extract feature description from branch name
FEATURE=$(echo "$BRANCH" | sed 's/claude\/\(.*\)-[0-9A-Za-z]\{20,\}/\1/' | tr '-' ' ')
TITLE="feat: ${FEATURE^}"

# Create PR body
PR_BODY="$(cat <<EOF
## Summary

This PR implements ${FEATURE}.

### Changes
$(git log ${BASE_BRANCH}...HEAD --pretty=format:"- %s" | head -10)

### Stats
- **Files changed**: $FILES_CHANGED
- **Lines added**: $LINES_ADDED
- **Lines removed**: $LINES_REMOVED

### Test Plan
- [ ] Code builds successfully
- [ ] Tests pass
- [ ] Manual testing completed
- [ ] Documentation updated

### Checklist
- [ ] Code follows project conventions
- [ ] No console errors or warnings
- [ ] Security considerations reviewed
- [ ] Performance impact assessed

---
*Generated by Claude Code session*
EOF
)"

# Push if needed
echo "Ensuring branch is pushed..."
git push -u origin "$BRANCH" 2>&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

<!-- .github/PULL_REQUEST_TEMPLATE.md -->

## Description
<!-- Describe your changes in detail -->

## 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