Branch Management

Overview

In .git, a branch is a lightweight pointer to a specific commit. Branches enable parallel development, feature isolation, release staging, and rapid hotfix deployment without disrupting the main codebase.

Branch Types

Lifecycle & States

Every branch in .git transitions through a defined lifecycle. States are automatically updated based on activity, merge status, and retention policies.

CLI Reference

$ .git branch create feature/user-profile
✓ Created branch 'feature/user-profile' from 'develop'
$ .git branch switch feature/user-profile
✓ Switched to 'feature/user-profile'

$ .git branch sync --all --remote origin
✓ Fetched 12 refs, pruned 4 stale branches
⚠ 3 branches require rebasing due to fast-forward divergence

$ .git branch merge feature/auth --into main --squash
✓ Squash merged into 'main' [3 commits]
$ .git branch delete feature/auth --remote
✓ Deleted remote branch 'refs/heads/feature/auth'

Naming Conventions

.git enforces semantic branch naming to improve traceability, automation, and audit compliance.

• feature/<ticket>-<short-desc> → New capabilities
• fix/<ticket>-<short-desc> → Bug resolutions
• release/v<x.y.z> → Version staging
• hotfix/<issue>-<short-desc> → Critical patches
• chore/<scope> → Dependencies, CI, configs

Protection Rules

Branch protection prevents accidental degradation of critical code paths. Rules are evaluated in real-time before merges or force-pushes.

Auto-Cleanup & Retention

To maintain repository hygiene, .git automatically manages merged and abandoned branches.

{
  "cleanup_policy": {
    "merged_retention_days": 3,
    "stale_retention_days": 30,
    "archive_metadata": true,
    "notify_owners": true,
    "allowed_patterns": ["main", "develop", "release/*", "hotfix/*"]
  }
}

Configure retention via the Platform Dashboard or .git/config/branch-lifecycle.yaml. Overrides require admin:branches scope.

FAQ

Troubleshooting