git-best-practices

Git Best Practices

Always Active Principles

When this skill is loaded, follow these directives for all git operations:

1. Discover before acting — run branch discovery to determine the repo's default and production branches before branching, merging, or opening PRs
2. Conventional commits — every commit uses type(scope): description format
3. Stage explicitly — add files by name so only intended changes are committed
4. Protect shared history — use --force-with-lease for force pushes; confirm with the user before any force push

Agent Git Workflow

1. Check state — run git status and git diff HEAD
2. Discover branches — identify default/current/(optional) production branch names (see Branch Discovery)
3. Stage by name — git add path/to/file for each file; verify with git status
4. Write a conventional commit — type(scope): description with optional body
5. Push safely — regular push by default; git push --force-with-lease origin {branch} only for rewritten history after user confirmation

Checkpoint Commits

Agents may create WIP checkpoint commits during long-running tasks, cleaned up before PR.

• Prefix with wip: or use standard conventional commit format
• Keep changes logically grouped even in WIP state
• Run /rewrite-history before opening a PR to craft a clean narrative

Commit Discipline

• Stage files explicitly by name: git add src/auth.ts src/auth.test.ts
• Verify staged content with git status before committing
• Keep secrets, .env files, credentials, and large binaries out of commits — warn the user if staged files look sensitive
• Target one logical change per commit in final PR-ready state

Force Push

Use --force-with-lease exclusively to protect against overwriting upstream changes:

git push --force-with-lease origin feat/my-branch

Always confirm with the user before any force push, regardless of branch.

Rebasing a Stack

When rebasing a branch that other branches are stacked on (e.g. phased NN-description chains), use git rebase --update-refs so the stacked branches follow the rewrite instead of being orphaned on the old commits. --update-refs moves local refs only — each moved branch that also exists on the remote still needs its own --force-with-lease push (after confirmation), and any branch checked out in another worktree is skipped. For the full conflict-resolution and safety workflow, use the git-rebase-sync skill.