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.sh"

npx --no -- commitlint --edit "$1"

# Install commitlint
npm install --save-dev @commitlint/cli @commitlint/config-conventional

# commitlint.config.js
echo "module.exports = { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js

Recover lost commits with reflog

The reflog records every HEAD movement. Use it when a rebase, reset, or amend discards commits you still need.

# View full reflog with timestamps
git reflog --date=relative

# Example reflog output:
# a1b2c3d HEAD@{0}: rebase (finish): returning to refs/heads/feat/search
# d4e5f6g HEAD@{1}: rebase (pick): fix: handle empty results
# e7f8g9h HEAD@{2}: rebase (start): checkout main
# f0a1b2c HEAD@{3}: commit: feat: add search indexing  <-- the lost commit

# Recover by creating a branch at the lost commit SHA or reflog entry:
git checkout -b recovery/lost-search-indexing HEAD@{3}
# or
git checkout -b recovery/lost-search-indexing f0a1b2c

# Cherry-pick recovered commit onto your branch:
git checkout feat/search
git cherry-pick f0a1b2c

To recover a dropped stash:

# Find dangling commits (stashes are commits)
git fsck --lost-found | grep commit

# Inspect each dangling commit to find your stash content:
git show <dangling-sha>

# Apply the recovered stash:
git stash apply <dangling-sha>

Cherry-pick specific commits across branches

Cherry-pick copies a commit (or range of commits) onto the current branch by replaying its diff.

# Cherry-pick a single commit by SHA
git cherry-pick a1b2c3d

# Cherry-pick a range (inclusive on both ends)
git cherry-pick a1b2c3d^..f0e9d8c

# Cherry-pick without immediately committing (stage only)
git cherry-pick --no-commit a1b2c3d

# If cherry-pick conflicts, resolve then:
git add <resolved-files>
git cherry-pick --continue

# Abort cherry-pick:
git cherry-pick --abort

Use -x to annotate the cherry-picked commit message with the original SHA:

git cherry-pick -x a1b2c3d
# Adds "(cherry picked from commit a1b2c3d)" to the commit message

Resolve complex merge conflicts

When branches have diverged significantly, use a three-way merge tool.

# See all conflicted files
git diff --name-only --diff-filter=U

# Open a visual merge tool (configured via git config merge.tool)
git mergetool

# For a specific file, compare all three versions:
git show :1:src/app.ts   # common ancestor
git show :2:src/app.ts   # ours (current branch)
git show :3:src/app.ts   # theirs (incoming branch)

# Accept ours or theirs entirely for a file:
git checkout --ours src/app.ts
git checkout --theirs src/app.ts

# After resolving all conflicts:
git add .
git merge --continue

# If the merge is unrecoverable:
git merge --abort

For a long-lived feature branch, prefer rebase over merge to replay commits on top of main one at a time - resolving smaller, isolated conflicts rather than one massive merge conflict.

---

Error handling

Error	Cause	Resolution
CONFLICT (content): Merge conflict in <file>	Two branches modified the same lines differently	Open file, resolve <<<<<<< markers, git add <file>, then git rebase --continue or git merge --continue
error: cannot rebase: You have unstaged changes	Working tree is dirty when starting rebase	git stash, rebase, then git stash pop
fatal: refusing to merge unrelated histories	Two repos with no common ancestor being merged	Use git merge --allow-unrelated-histories once; investigate why histories diverged
error: failed to push some refs after rebase	Remote has diverged (rebased shared history)	If the branch is yours alone: git push --force-with-lease. If shared: do not force-push, merge instead
detached HEAD state after bisect/checkout	HEAD points to commit SHA, not a branch	git checkout -b <new-branch> to save work, or git checkout <branch-name> to return
Your local changes would be overwritten by checkout	Uncommitted changes conflict with target branch	Commit or stash changes first: git stash push -m "wip: context", then switch branches

---

Gotchas

1. Interactive rebase on commits already pushed to a shared branch will break teammates - git rebase -i rewrites SHAs. If anyone has already pulled those commits, their history diverges and they face painful force-merge situations. Only interactively rebase commits that exist solely on your local or personal feature branch. Use git push --force-with-lease (never bare --force) if you must update a remote branch you own.

2. git bisect reset is not optional - If you forget to run git bisect reset after a bisect session, HEAD remains detached at whatever commit bisect last checked out. Any work you commit in this state is not on any branch and is easily lost. Always run git bisect reset before returning to normal development.

3. Worktrees sharing the same branch causes confusing conflicts - Git prevents two worktrees from checking out the exact same branch simultaneously, but it's easy to accidentally make changes in one worktree that affect the index visible in another. Keep one branch per worktree and run git worktree prune after removing worktree directories to prevent stale lock files.

4. Reflog entries expire - you cannot recover commits after git gc runs - The default reflog expiry is 90 days, but git gc may run automatically. Once a commit's reflog entry is gone and it's unreachable from any branch, git fsck --lost-found is your last hope. When recovering, create a new branch immediately rather than cherry-picking from a detached state.

5. Cherry-picking merge commits requires -m to specify the mainline - Running git cherry-pick <merge-commit-sha> without specifying a parent number will fail with an error. You must supply -m 1 (or -m 2) to tell git which side of the merge is the mainline. For most cases, -m 1 picks the changes relative to the first parent (the branch that was merged into).

---

References

For detailed content on specific topics, read the relevant file from references/:

• references/rebase-strategies.md - Rebase workflows, when to rebase vs merge, interactive rebase recipes for common scenarios

Only load a references file if the current task requires deep detail on that topic.