Branching Skill

Production-Grade Development Skill | Version 2.0.0

Effective branching and merging strategies for development workflows.

Skill Contract

Input Schema

input:
  type: object
  properties:
    operation:
      type: string
      enum: [create, switch, merge, rebase, delete, list, strategy]
      default: list
    branch_name:
      type: string
      pattern: "^[a-zA-Z0-9/_-]+$"
      maxLength: 100
    strategy:
      type: string
      enum: [gitflow, github-flow, trunk-based]
    options:
      type: object
      properties:
        force:
          type: boolean
          default: false
        dry_run:
          type: boolean
          default: false

Output Schema

output:
  type: object
  required: [result, success]
  properties:
    result:
      type: string
    success:
      type: boolean
    branches_affected:
      type: array
      items:
        type: string
    warnings:
      type: array
    rollback_command:
      type: string

Error Handling

Retry Logic

retry_config:
  max_attempts: 2
  backoff_ms: [1000, 2000]
  retryable:
    - lock_file_exists
    - network_timeout
  non_retryable:
    - merge_conflict
    - branch_not_found

Fallback Strategy

fallback:
  - trigger: merge_conflict
    action: abort_and_guide_manual_resolution
    command: git merge --abort
  - trigger: rebase_conflict
    action: abort_and_suggest_merge
    command: git rebase --abort

---

Branch Basics

# List branches
git branch              # Local branches
git branch -r           # Remote branches
git branch -a           # All branches

# Create branch
git branch feature-x    # Create only
git checkout -b feature-x  # Create and switch
git switch -c feature-x    # Modern syntax

# Switch branches
git checkout main
git switch main         # Modern syntax

# Delete branch
git branch -d feature-x     # Safe delete
git branch -D feature-x     # Force delete
git push origin --delete feature-x  # Delete remote

Branching Strategies

GitFlow

┌─────────────────────────────────────────────────────────────┐
│                       GITFLOW                               │
├─────────────────────────────────────────────────────────────┤
│ main    ●─────────────────●───────────────●──────────►     │
│          ↑                 ↑               ↑                │
│ release  ├─────●───────────┤               │                │
│          │     ↑           │               │                │
│ develop  ├──●──┴──●──●──●──┴──●──●──●──●──┴──●──●──────►   │
│          │  ↑     ↑     ↑     ↑     ↑                       │
│ feature  └──┴─────┴─────┴─────┴─────┘                       │
└─────────────────────────────────────────────────────────────┘

GitHub Flow (Simpler)

┌─────────────────────────────────────────────────────────────┐
│                     GITHUB FLOW                             │
├─────────────────────────────────────────────────────────────┤
│ main     ●────────●────────●────────●────────●─────────►   │
│           \      ↑  \     ↑  \     ↑                        │
│ feature    \────●    \───●    \───●                         │
│            (PR)     (PR)     (PR)                           │
└─────────────────────────────────────────────────────────────┘

Trunk-Based Development

┌─────────────────────────────────────────────────────────────┐
│                  TRUNK-BASED DEV                            │
├─────────────────────────────────────────────────────────────┤
│ main    ●──●──●──●──●──●──●──●──●──●──●──●──●─────────►    │
│            ↑  ↑  ↑  ↑  ↑  ↑  ↑  ↑  ↑  ↑  ↑                 │
│          (frequent small commits to main)                   │
└─────────────────────────────────────────────────────────────┘

Merging Strategies

Strategy	Command	Use Case
Fast-Forward	git merge feature	Linear history
Three-Way	git merge feature	Diverged branches
Squash	git merge --squash feature	Clean history

Rebasing

Rebase vs Merge

Aspect	Merge	Rebase
History	Preserves	Linear
Safety	Shared branches OK	Never on shared
Conflicts	Resolve once	May resolve multiple

---

Troubleshooting Guide

Debug Checklist

□ 1. Current branch? → git branch
□ 2. Uncommitted changes? → git status
□ 3. Diverged? → git log --oneline main..HEAD

Common Issues

Error	Cause	Solution
"already exists"	Branch name taken	Use different name
"not fully merged"	Unmerged commits	Use -D or merge first
"CONFLICT"	Divergent changes	Resolve manually

---

Observability

logging:
  level: INFO
  events:
    - branch_created
    - merge_completed
    - conflict_detected

metrics:
  - branches_per_repo
  - merge_conflict_rate

---

Best Practices

1. Descriptive names: feature/user-auth, fix/login-bug
2. Short-lived branches: Merge frequently
3. Delete merged branches: Avoid clutter

---

"Branches are cheap in Git - use them liberally."