Git (Essentials + Workflows + Advanced)

Setup

On first use, read setup.md. Default: best practices mode (no config needed).

When to Use

User needs Git expertise — from basic operations to complex workflows. Agent handles branching, merging, rebasing, conflict resolution, and team collaboration patterns.

Architecture

Memory in ~/git/. See memory-template.md for structure.

~/git/
└── memory.md    # User preferences (optional)

Quick Reference

Core Rules

1. Never force push to shared branches — Use --force-with-lease on feature branches only
2. Commit early, commit often — Small commits are easier to review, revert, and bisect
3. Write meaningful commit messages — First line under 72 chars, imperative mood
4. Pull before push — Always git pull --rebase before pushing to avoid merge commits
5. Clean up before merging — Use git rebase -i to squash fixup commits

Team Workflows

Feature Branch Flow:

1. git checkout -b feature/name from main
2. Make commits, push regularly
3. Open PR, get review
4. Squash and merge to main
5. Delete feature branch

Hotfix Flow:

1. git checkout -b hotfix/issue from main
2. Fix, test, commit
3. Merge to main AND develop (if exists)
4. Tag the release

Daily Sync:

git fetch --all --prune
git rebase origin/main  # or merge if team prefers

Commit Messages

• Use conventional commit format: type(scope): description
• Keep first line under 72 characters
• Types: feat, fix, docs, style, refactor, test, chore

Push Safety

• Use git push --force-with-lease instead of --force — prevents overwriting others' work
• If push rejected, run git pull --rebase before retrying
• Never force push to main/master branch

Conflict Resolution

• After editing conflicted files, verify no markers remain: grep -r "<<<\|>>>\|===" .
• Test that code builds before completing merge
• If merge becomes complex, abort with git merge --abort and try git rebase instead

Branch Hygiene

• Delete merged branches locally: git branch -d branch-name
• Clean remote tracking: git fetch --prune
• Before creating PR, rebase feature branch onto latest main
• Use git rebase -i to squash messy commits before pushing

Safety Checklist

Before destructive operations (reset --hard, rebase, force push):

• Is this a shared branch? → Don't rewrite history
• Do I have uncommitted changes? → Stash or commit first
• Am I on the right branch? → git branch to verify
• Is remote up to date? → git fetch first

Common Traps