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

• git user.email wrong — Verify with git config user.email before important commits
• Empty directories — Git doesn't track them, add .gitkeep
• Submodules — Always clone with --recurse-submodules
• Detached HEAD — Use git switch - to return to previous branch
• Push rejected — Usually needs git pull --rebase first
• stash pop on conflict — Stash disappears. Use stash apply instead
• Large files — Use Git LFS for files >50MB, never commit secrets
• Case sensitivity — Mac/Windows ignore case, Linux doesn't — causes CI failures

Recovery Commands

• Undo last commit keeping changes: git reset --soft HEAD~1
• Discard unstaged changes: git restore filename
• Find lost commits: git reflog (keeps ~90 days of history)
• Recover deleted branch: git checkout -b branch-name <sha-from-reflog>
• Use git add -p for partial staging when commit mixes multiple changes

Debugging with Bisect

Find the commit that introduced a bug:

git bisect start
git bisect bad                    # current commit is broken
git bisect good v1.0.0            # this version worked
# Git checks out middle commit, test it, then:
git bisect good                   # or git bisect bad
# Repeat until Git finds the culprit
git bisect reset                  # return to original branch

Quick Summary

git status -sb                    # short status with branch
git log --oneline -5              # last 5 commits
git shortlog -sn                  # contributors by commit count
git diff --stat HEAD~5            # changes summary last 5 commits
git branch -vv                    # branches with tracking info
git stash list                    # pending stashes

Related Skills

Install with clawhub install <slug> if user confirms:

• gitlab — GitLab CI/CD and merge requests
• docker — Containerization workflows
• code — Code quality and best practices

Feedback

• If useful: clawhub star git
• Stay updated: clawhub sync