When this skill is activated, always start your first response with the 🧢 emoji.

Git Advanced

Git is a distributed version control system built on a directed acyclic graph (DAG) of immutable commit objects. Most developers use only 20% of git's power - add, commit, push, pull. The remaining 80% covers the workflows that separate a junior from a senior: precise history rewriting with interactive rebase, surgical bug hunting with bisect, parallel development with worktrees, automated quality gates with hooks, and safe history recovery with reflog. This skill equips an agent to handle any advanced git task with confidence.

When to use this skill

Trigger this skill when the user:

• Wants to squash, fixup, reorder, or edit commits with interactive rebase
• Needs to find the exact commit that introduced a bug (git bisect)
• Wants to work on multiple branches simultaneously without stashing (worktrees)
• Needs to set up pre-commit, commit-msg, or other git hooks
• Wants to cherry-pick specific commits across branches
• Has lost commits, stashes, or rebased away work and needs recovery
• Needs to handle a complex merge conflict with diverged histories
• Asks about stash management, patch workflows, or reflog navigation

Do NOT trigger this skill for:

• Basic git operations (add, commit, push, pull, clone) - no skill needed
• Repository hosting platform features (GitHub PRs, GitLab MRs, Bitbucket pipelines)

Key principles

1. Commit often, rebase before push - Small, frequent commits preserve context and make bisect effective. Before pushing to a shared branch, use interactive rebase to clean the history into logical, reviewable units.

2. Never rewrite shared history - Any branch that others have checked out must not be force-pushed. Rebase and amend only on local branches or feature branches you own. git push --force-with-lease over --force if you must.

3. Atomic commits - Each commit should represent one logical change that leaves the codebase in a working state. An atomic commit can be reverted or cherry-picked without side effects. If your commit message needs "and", split the commit.

4. Branch naming conventions - Use prefixes to communicate intent: feat/, fix/, chore/, refactor/, docs/. Include a ticket number when applicable: feat/PROJ-123-user-auth. Lowercase, hyphens, no spaces.

5. Hooks prevent bad commits - Git hooks are the last line of defense before code enters the repository. Pre-commit hooks run linters and formatters; commit-msg hooks enforce message conventions; pre-push hooks run tests. Automate quality at the source.

Core concepts

DAG model - Git history is a directed acyclic graph where each commit points to its parent(s). A commit is identified by a SHA-1 hash of its content, parent hashes, author, and message. Branches are just named pointers to commits. Understanding the DAG explains why rebasing "moves" commits (it creates new ones) and why merge creates a commit with two parents.

Refs, HEAD, and detached HEAD - HEAD is a pointer to the currently checked-out commit. Normally it points to a branch ref (refs/heads/main), which points to a commit. "Detached HEAD" means HEAD points directly to a commit SHA, not a branch. This happens during rebase, bisect, and git checkout <sha>. Always create a branch before committing in detached HEAD state.

Rebase vs merge - Both integrate changes from one branch into another, but with different history shapes. Merge preserves the true history with a merge commit (two parents). Rebase replays commits on top of the target, producing a linear history but rewriting SHAs. Use merge for integrating shared branches (main, develop); use rebase to keep feature branches current and clean before merging. See references/rebase-strategies.md for detailed decision guidance.

Reflog as safety net - The reflog (git reflog) records every position HEAD has been at, including rebases, resets, and amends. It retains entries for 90 days by default. Any commit that was ever reachable is recoverable via reflog - it is the ultimate undo mechanism. Nothing is truly lost until git gc runs and the reflog entries expire.

Common tasks

Interactive rebase - squash, fixup, and reorder commits

Use interactive rebase to clean up local history before pushing. Always target a commit that is not on a shared branch.

# Rebase last N commits interactively
git rebase -i HEAD~5

# Rebase all commits since branching from main
git rebase -i $(git merge-base HEAD main)

In the editor that opens, each line is a commit with an action keyword:

pick a1b2c3 feat: add login page
pick d4e5f6 wip: half-done validation
pick g7h8i9 fix typo
pick j0k1l2 fix: complete validation logic
pick m3n4o5 chore: remove console.logs

Change keywords to reshape history:

• squash (s) - merge into previous commit, combine messages
• fixup (f) - merge into previous commit, discard this message
• reword (r) - keep commit but edit the message
• edit (e) - pause rebase to amend the commit
• drop (d) - delete the commit entirely
• Reorder lines to reorder commits

pick a1b2c3 feat: add login page
fixup g7h8i9 fix typo
squash j0k1l2 fix: complete validation logic
fixup d4e5f6 wip: half-done validation
drop m3n4o5 chore: remove console.logs

If conflicts arise during rebase:

# Resolve conflicts in the marked files, then:
git add <resolved-files>
git rebase --continue

# To abort and return to original state:
git rebase --abort

Git bisect to find the commit that introduced a bug

Bisect performs a binary search through commit history to find the first bad commit. It requires you to identify one good commit and one bad commit.

# Start bisect session
git bisect start

# Mark the current commit as bad (has the bug)
git bisect bad

# Mark a known-good commit (before the bug existed)
git bisect good v2.1.0
# or by SHA:
git bisect good a1b2c3d

# Git checks out the midpoint - test, then mark:
git bisect good   # if this commit does NOT have the bug
git bisect bad    # if this commit DOES have the bug

# Repeat until git identifies the first bad commit.
# When done, reset to original branch:
git bisect reset

Automate bisect with a test script (exit 0 = good, exit 1 = bad):

git bisect start
git bisect bad HEAD
git bisect good v2.1.0
git bisect run npm test -- --testNamePattern="the failing test"
git bisect reset

Manage worktrees for parallel work

Worktrees allow multiple working directories from a single repository, each on a different branch. No stashing needed to switch context.

# List existing worktrees
git worktree list

# Add a new worktree for a feature branch (sibling directory)
git worktree add ../project-hotfix fix/PROJ-456-crash

# Add a worktree for a new branch that doesn't exist yet
git worktree add -b feat/PROJ-789-search ../project-search main

# Work in the worktree directory normally - all git operations are branch-specific
cd ../project-hotfix
git log --oneline -5

# Remove a worktree when done
git worktree remove ../project-hotfix

# Prune stale worktree references (if directory was manually deleted)
git worktree prune

Set up pre-commit hooks with Husky

Husky manages git hooks via npm scripts, checked into the repository so all team members share the same hooks.

# Install husky
npm install --save-dev husky

# Initialize husky (creates .husky/ directory and sets core.hooksPath)
npx husky init

Create .husky/pre-commit:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx lint-staged

Configure lint-staged in package.json:

{
  "lint-staged": {
    "*.{js,ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{css,md,json}": ["prettier --write"]
  }
}

Create .husky/commit-msg to enforce conventional commits:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.