---
name: pro-git
description: >-
  Expert Git knowledge distilled from the Pro Git book (2nd edition, Chacon &
  Straub). Use when working with Git version control: everyday commands
  (add/commit/log/diff), branching and merging, rebasing, undoing mistakes,
  rewriting history, recovering lost commits, resolving merge conflicts,
  remotes and collaboration workflows, tags, stashing, bisect/blame debugging,
  submodules, hooks, git configuration and attributes, setting up a Git
  server, or understanding Git internals (objects, refs, packfiles, refspecs).
---

# Pro Git

Knowledge base built from the Pro Git book (2nd ed., covering Git 2.x including
`git switch`/`git restore`, `init.defaultBranch`, and modern guidance such as
preferring `git-filter-repo` over `filter-branch`).

## How to use this skill

1. Identify the task category below.
2. Read the matching reference file in `references/` for accurate commands,
   options, and pitfalls before acting.
3. For "which command does X" lookups, start with
   `references/command-index.md`.

| Task | Reference |
|---|---|
| First-time setup, staging, committing, log, diff, ignoring files, basic undo, remotes, tags, aliases | `references/basics.md` |
| Branches, merging, conflicts, remote-tracking branches, rebasing, branch workflows | `references/branching.md` |
| Team workflows, commit message guidelines, contributing/maintaining projects, email patches, GitHub flow | `references/collaboration.md` |
| Amending, interactive rebase, squash/split/reorder commits, reset vs checkout (three trees), reflog, data recovery, removing files from history | `references/history-and-recovery.md` |
| Revision syntax (`HEAD~`, `A..B`, `A...B`), stash, clean, bisect, blame, advanced merge tools, rerere, signing, searching, submodules, bundling, credential storage | `references/advanced-tools.md` |
| Protocols (SSH/HTTP/Git/local), bare repos, setting up a server, hosting options | `references/server.md` |
| git config reference, .gitattributes (line endings, binary diff, merge strategies, filters), hooks, enforced policy | `references/customization.md` |
| Internals: objects, refs, packfiles, refspecs, transfer protocols, gc, fsck, environment variables | `references/internals.md` |
| Command → purpose → where covered lookup table | `references/command-index.md` |

## Core mental model (always keep in mind)

- Git stores **snapshots, not diffs**. Nearly every operation is local, and
  everything is checksummed (SHA-1) and referenced by that hash.
- Files move through **three states**: modified (working tree) → staged
  (index/staging area) → committed (`.git` database). `git add` means "add
  precisely this content to the next commit".
- A **branch is just a 41-byte movable pointer** to a commit; `HEAD` points to
  the current branch. This makes branching cheap — use topic branches freely.
- **Committed data is almost never lost** (reflog + fsck can recover it);
  uncommitted changes destroyed by `reset --hard`, `checkout -- <file>`,
  `restore`, or `clean` are usually gone forever. Treat those commands as
  dangerous.
- **Never rewrite history that others may have based work on** (no
  amend/rebase/force-push of pushed commits). Rebase local cleanup is fine and
  encouraged before sharing.

## Quick answers to the most common requests

- Unstage a file: `git restore --staged <file>` (older: `git reset HEAD <file>`)
- Discard local file changes (destructive): `git restore <file>` (older: `git checkout -- <file>`)
- Fix the last commit: `git commit --amend` (`--no-edit` to keep the message; local commits only)
- What am I about to push: `git log origin/master..HEAD`
- Recover a "lost" commit: `git reflog` → `git branch recover-branch <sha>`
- Find the commit that broke things: `git bisect start` / `bad` / `good` (or `git bisect run <script>`)
- Who wrote this line: `git blame -L <start>,<end> <file>` (`-C` traces code moved between files)
- Temporarily shelve work: `git stash` → `git stash pop` (`-u` to include untracked files)