Working with Git

Offline reference for Git the version-control system, pinned to a known Git release (see PINNED_VERSION / references/VERSIONS.md, resolved via Homebrew). Command and concept pages in references/cli/ are the AsciiDoc sources from git/git at the pinned tag; the full Pro Git book (2nd ed.) is in references/book/; opinionated how-to guides are in references/howto/. Fetched files carry source/fetched_at/sha256 frontmatter; the how-to guides are hand-written.

Scope / where to go instead

• GitHub (gh CLI, PRs, REST/GraphQL, releases, issues) → working-with-github
• CI/CD workflows → working-with-github-actions
• Building GitHub Apps / Octokit → developing-for-github
• This skill = raw git only.

Quick reference

Task	Read
Exact flags for a command	references/cli/git-<command>.adoc (e.g. git-rebase.adoc, git-commit.adoc)
Concept page (attributes, hooks, revisions, glossary)	references/cli/git<topic>.adoc (e.g. gitrevisions.adoc, githooks.adoc, gitglossary.adoc)
Learn a topic deeply	references/book/*.asc (Pro Git, e.g. 03-git-branching__*)
Rewrite history safely	references/howto/rewriting-history.md
Find the commit that broke it	references/howto/bisect.md
Undo / recover (reflog, reset/revert/restore, lost commits)	references/howto/fixing-mistakes.md
Merge vs rebase, resolve conflicts, rerere	references/howto/merging-and-conflicts.md
Host or connect to a Git server	references/howto/git-servers.md
Worktree conventions for feature/parallel-agent work	references/howto/worktree-conventions.md

How to use this skill

1. Exact command behavior/flags — read references/cli/git-<command>.adoc. These are the literal man-page sources for the pinned Git version; trust your local git help <command> if it disagrees and surface the drift.
2. Conceptual understanding — read the relevant Pro Git chapter in references/book/ (filenames are the chapter path flattened with __).
3. "How do I safely do X" — start with references/howto/*.md; these are the opinionated playbooks for the dangerous/confusing operations.
4. Searching — grep -ri <term> references/ across all three.

Behavioral guidance

• History rewriting is destructive. On shared branches, always git push --force-with-lease (never bare --force), and confirm no one else has the branch. See references/howto/rewriting-history.md.
• git stash drops untracked files unless you pass -u. Reach for git stash -u when in doubt.
• Reflog is the safety net — almost any "lost" commit is recoverable via git reflog for ~90 days. Check it before declaring data lost.

Keeping this current

Regenerated by scripts/update_docs.js: it re-resolves the Git stable version from Homebrew, rewrites PINNED_VERSION, fetches the matching git/git AsciiDoc, and refetches Pro Git. Refresh locally with make update-working-with-git. In CI (no Homebrew) the committed pin tag is used unchanged.