From c664c69f67c308394c107b6e47ca1919e7726b51 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 4 Aug 2026 06:27:16 +0000 Subject: [PATCH 1/2] Update progress.asc to the new outline and chapter numbering Reorganize the task list around OUTLINE.md: new chapter numbers and titles, a Restructure section with the completed work checked off, X1-X6 sweeps matching the outline's numbering (X4/X5 done), sections for the new Git and Agents and Git at Scale chapters, and per-chapter tasks updated for the restructured files. 15 of 101 tasks done. Co-authored-by: Scott Chacon --- progress.asc | 145 ++++++++++++++++++++++++++++++++------------------- 1 file changed, 92 insertions(+), 53 deletions(-) diff --git a/progress.asc b/progress.asc index bbbd6ba..9622de0 100644 --- a/progress.asc +++ b/progress.asc @@ -1,10 +1,11 @@ = Pro Git, 3rd Edition — Progress :toc: -Working task list for the third edition, derived from the chapter-by-chapter -inventory in `REVISION_PLAN.md`. This file is edited by hand: mark a task done by -changing `[ ]` to `[x]`, and add new tasks — or whole new sections — as they come -up. The site's progress page renders this file directly, so keep the format: +Working task list for the third edition. The canonical chapter/section outline and +punch list is `OUTLINE.md` (chapter numbers below follow it); the content-level +inventory behind it is `REVISION_PLAN.md`. This file is edited by hand: mark a task +done by changing `[ ]` to `[x]`, and add new tasks — or whole new sections — as they +come up. The site's progress page renders this file directly, so keep the format: `== Section title` headings with `* [ ]` checklist items under them. == Project setup @@ -14,6 +15,17 @@ up. The site's progress page renders this file directly, so keep the format: * [x] Build the line-level `master` -> `main` inventory (`book_master_to_main_inventory.md`) * [x] Launch the project site — book reader, blog, history * [x] Set up the cloud build/test environment for agents +* [x] Link ebook downloads (PDF/EPUB/FB2/HTML) from the site's book page +* [x] Switch the PDF code font to JetBrains Mono + +== Restructure + +* [x] Write the full chapter/section outline and punch list (`OUTLINE.md`) +* [x] Renumber and retitle the chapters (Git Toolkit, Git Servers, new order) +* [x] Create the new placeholder chapters — Git and Agents (Ch 7), Git at Scale (Ch 9) +* [x] Create the new placeholder sections — Worktrees (3.5), Pull Requests and Forges (4.3), Ignoring Files (6.2) +* [x] Drop the GitHub chapter, Git and Other Systems, and the environments/embedding appendices; keep the command reference as Appendix A +* [x] Retarget every cross-reference; render xrefs as chapter labels instead of filenames == Policy decisions @@ -24,12 +36,19 @@ These gate the cross-cutting sweeps; decide them first. == Cross-cutting sweeps +Numbered as in `OUTLINE.md`. + * [ ] X1 — `master` -> `main` across the book (see the inventory for the per-line breakdown) -* [ ] X1 — regenerate diagrams and screenshots that show a `master` branch -* [ ] X2 — SHA-1 -> SHA-256 default-hash pass (~31 files reference hashes) +* [ ] X2 — SHA-1 -> SHA-256 example-hash pass (~31 files reference hashes) * [ ] X3 — version framing: bump "written using Git version 2" to 3.x; reframe "since Git 2.23/2.27/2.28" notes as baseline behavior -* [ ] X4 — cover the `safe.bareRepository` and `safe.directory` security defaults -* [ ] X5 — forge/IDE screenshot refresh (Ch 4, Ch 6, Appendix A) +* [x] X4 — restructure plumbing: include map, chapter renumbering, placeholders, drops +* [x] X5 — cross-reference repair after the restructure (retargets, rescued anchors) +* [ ] X6 — regenerate diagrams for `main`; new diagrams for worktrees, agents, and scale + +== Preface + +* [ ] Write the preface — the 3.0 moment, new-defaults-first stance, dual-path coverage, what's new this edition (outline placeholder is in place) +* [ ] Decide: fold `introduction.asc` into the preface, or keep it standalone == Chapter 1 — Getting Started @@ -38,96 +57,116 @@ These gate the cross-cutting sweeps; decide them first. * [ ] Add the Rust toolchain requirement to "compile from source" * [ ] Rewrite the default-branch subsection of `first-time-setup.asc` for a main-default world * [ ] Note Git's maturation and the 3.0 transition in the history section +* [ ] Refresh the help-channels list in `help.asc` == Chapter 2 — Git Basics -* [ ] Normalize `restore`/`switch` as standard commands (drop the "new in 2.23" framing) -* [ ] Decide whether to teach `restore`/`switch` before `checkout`/`reset` +* [ ] Reframe `undoing.asc` around `restore`/`switch` as the primary verbs +* [ ] Note what `git init` creates under 3.0 (`main`, SHA-256, reftable) in `getting-a-repository.asc`; demote `git://` * [ ] Update the `pull.rebase` warning framing in `remotes.asc` +* [ ] Assemble 2.7 "Basic Configuration and Aliases" from the existing config material * [ ] Regenerate example hashes per the X2 policy -* [ ] Note the `main` and reftable defaults in `getting-a-repository.asc` == Chapter 3 — Git Branching * [ ] X1 sweep (101 renames — the heaviest concentration) * [ ] Regenerate the branch diagrams in `diagram-source/` +* [ ] Teach `git switch` first in `nutshell.asc`; `checkout` as the legacy form * [ ] Revisit the branch-renaming discussion in `branch-management.asc` for a main-default world +* [ ] Add GitHub Flow, trunk-based development, and stacked PRs to `workflows.asc` +* [ ] Write 3.5 Worktrees (placeholder is in place; new diagrams needed) -== Chapter 4 — Git on the Server - -* [ ] Demote Gitweb and `git daemon`; lead with modern self-hosting -* [ ] Add Gitea/Forgejo coverage -* [ ] Cover protocol v2; retire dumb HTTP -* [ ] Recommend Ed25519 keys in `generating-ssh-key.asc` -* [ ] Add a sidebar on reftable and SHA-256 hosting/interop implications -* [ ] Refresh screenshots (X5) - -== Chapter 5 — Distributed Git +== Chapter 4 — Distributed Git * [ ] X1 sweep (`contributing` 48 renames, `maintaining` 39) -* [ ] Contextualize the email-based workflow against PR-based norms - -== Chapter 6 — GitHub +* [ ] Contextualize the email-based workflow as the kernel/git.git niche +* [ ] Add trunk-based development to `distributed-workflows.asc` +* [ ] Write 4.3 Pull Requests and Forges, forge-neutral (placeholder and rescued anchors are in place; adapt the dropped GitHub-chapter material) +* [ ] Add the PR-based maintenance counterpart to `maintaining.asc` +* [ ] Rewrite the chapter close (the old "next chapter: GitHub" handoff — flagged with an AUTHOR TODO) -* [ ] Re-capture all screenshots (X5) -* [ ] Text pass for the current PR review UI, org settings, and account setup flows -* [ ] Scope decision on Actions, Codespaces, and the current review experience -* [ ] Default-branch language in examples (26 renames in `2-contributing`) - -== Chapter 7 — Git Tools +== Chapter 5 — Git Toolkit * [ ] Add SSH commit/tag signing to `signing.asc` (plus `gpgsm` for X.509) * [ ] Rework `replace.asc` — grafts are removed in 3.0 * [ ] Add the new `git history` command to `rewriting-history.asc` * [ ] Lead `rewriting-history.asc` with `git filter-repo`; mark `filter-branch` deprecated * [ ] Update `credentials.asc` for Git Credential Manager -* [ ] Add `git worktree` coverage -* [ ] Add `git sparse-checkout` coverage +* [ ] Update `stash save` -> `stash push` throughout `stashing-cleaning.asc` +* [ ] Add `git bisect run` to `debugging.asc` * [ ] Evaluate `git range-diff`, `git replay`, `git bugreport`, `git diagnose` for coverage * [ ] X1 sweep (147 renames — the highest chapter total) -== Chapter 8 — Customizing Git +== Chapter 6 — Customizing Git -* [ ] Add `safe.bareRepository` and `safe.directory` to `config.asc` (X4) +* [ ] Add `safe.bareRepository` and `safe.directory` to `config.asc` * [ ] Rewrite `init.defaultBranch` as default-is-main * [ ] Note `--object-format` (SHA-256) and `extensions.refStorage` (reftable) +* [ ] Add `includeIf`, `core.hooksPath`, and the XDG config path to `config.asc` * [ ] Note removed config: `core.commentString=auto`, `core.preferSymlinkRefs=true` -* [ ] Consider `git for-each-repo` in the scripting material +* [ ] Assemble 6.2 Ignoring Files from the Ch 2 and `config.asc` material (placeholder is in place) +* [ ] Refresh the hook catalog with post-2014 hooks +* [ ] Decide: keep `policy.asc` (recommended) or cut it * [ ] X1 sweep (`policy.asc` enforced-workflow example, 8 renames) -== Chapter 9 — Git and Other Systems +== Chapter 7 — Git and Agents + +All prose is new; section placeholders with outline notes are in place. + +* [ ] Write the chapter introduction — how agents change repository usage +* [ ] Write 7.1 Workflows for Agents +* [ ] Write 7.2 Tools and Interfaces +* [ ] Write 7.3 Libraries (reflow the dropped Appendix B; add gitoxide and per-library SHA-256 notes) +* [ ] Write 7.4 Guiding Agents +* [ ] Write 7.5 Tips and Pitfalls + +== Chapter 8 — Git Servers + +* [ ] Cover protocol v2; retire dumb HTTP +* [ ] Recommend Ed25519 keys in `generating-ssh-key.asc` +* [ ] Trim `git daemon`; drop the xinetd/sysvinit material +* [ ] Update `smart-http.asc` to current Apache syntax; note token/OIDC auth +* [ ] Decide: cut GitWeb to a sidebar (recommended) or keep it trimmed +* [ ] Rework 8.8 into a self-hosted forges section — Gitea/Forgejo lead, GitLab heavyweight (new screenshots) +* [ ] Rewrite 8.9 Hosted Options as the current hosting landscape +* [ ] Add a sidebar on reftable and SHA-256 hosting/interop implications +* [ ] Fix the chapter's "next chapter" prose for the new order (flagged with an AUTHOR TODO) + +== Chapter 9 — Git at Scale + +All prose is new; section placeholders with outline notes are in place. -* [ ] Trim `git svn` coverage -* [ ] Demote the Mercurial and Perforce bridges to a short "bridges exist" section -* [ ] Verify the bridge tooling runs on modern Python -* [ ] X1 sweep (23+ renames in the Hg sections, 37 in `git-p4`) +* [ ] Write the chapter introduction — why big repositories strain Git +* [ ] Write 9.1 Shallow Clones +* [ ] Write 9.2 Partial Clone +* [ ] Write 9.3 Sparse Checkout +* [ ] Write 9.4 Scalar +* [ ] Write 9.5 Keeping Large Repositories Fast +* [ ] Write 9.6 Large Files (decide: lives here, as recommended, or in Git Servers) +* [ ] Write 9.7 Monorepos +* [ ] Decide the performance split: ops story in 9.5, format detail in Ch 10 (recommended) == Chapter 10 — Git Internals * [ ] Rewrite `objects`/`packfiles` with the object-format framing and the SHA-256 interop story * [ ] Add reftable to `refs.asc` — the new default, and the why (case-collision, performance) * [ ] Fold protocol v2 into `transfer-protocols.asc` -* [ ] Verify `maintenance.asc` against current `git maintenance` -* [ ] Add `commit-graph` and `multi-pack-index` to the performance story +* [ ] Verify `maintenance.asc` against current `git maintenance`; redo the big-file removal example with `filter-repo` +* [ ] Add `commit-graph` and `multi-pack-index` format coverage * [ ] X1 sweep (70 renames) -== Appendices +== Appendix A — Git Commands -* [ ] Appendix A: version/screenshot refresh for Sublime Text, Visual Studio, VS Code, JetBrains IDEs -* [ ] Appendix A: version-check the shell completion sections -* [ ] Appendix B: refresh binding versions (`libgit2`, `jgit`, `go-git`, `dulwich`) -* [ ] Appendix B: promote `go-git`; add per-library SHA-256 support notes -* [ ] Appendix C: add post-2.1 commands to the command index; note the 3.0 removals +* [ ] Add post-2.1 commands to the index: `switch`, `restore`, `worktree`, `sparse-checkout`, `scalar`, `maintenance`, `range-diff`, `history` +* [ ] Note the 3.0 removals (`whatchanged`, `pack-redundant`) and deprecations (`filter-branch`) +* [ ] Decide the fate of the commented-out External Systems entries (`git svn`, `git fast-import`) == New material -* [ ] Dedicated "Git 3.0 / migrating to SHA-256" section -* [ ] Reftable explainer (pairs with the Ch 10 refs rewrite) -* [ ] Monorepo-scale material: sparse-checkout, partial clone, `scalar`, `git backfill` -* [ ] `git maintenance` + commit-graph as a first-class performance story +* [ ] Dedicated "Git 3.0 / migrating to SHA-256" section — decide where it lives, then write it == Publication * [ ] Redo the contributors list and dedication -* [ ] Final pass on the appendices (fastest to rot; do near publication) +* [ ] Final pass on the command appendix (fastest to rot; do near publication) * [ ] Watch for the LTS tag (the last 2.x before 3.0) and time the release to it From bfeaae580f16c4b9dc440df4d0326bcd8f1d0255 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 4 Aug 2026 06:27:16 +0000 Subject: [PATCH 2/2] Add blog post on the third edition's new table of contents Describes the restructure: the new chapter order, the two new chapters (Git at Scale, Git and Agents), the smaller additions (worktrees, forge-neutral pull requests, ignoring files), and what was dropped (GitHub chapter, other-systems chapter, two appendices). Written per BLOG_STYLE.md with automated: true. Co-authored-by: Scott Chacon --- .../content/blog/a-new-table-of-contents.mdx | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 site/src/content/blog/a-new-table-of-contents.mdx diff --git a/site/src/content/blog/a-new-table-of-contents.mdx b/site/src/content/blog/a-new-table-of-contents.mdx new file mode 100644 index 0000000..c18e099 --- /dev/null +++ b/site/src/content/blog/a-new-table-of-contents.mdx @@ -0,0 +1,62 @@ +--- +title: 'A new table of contents' +description: "The third edition's restructure has landed: two new chapters, a long-overdue worktrees section, and a few goodbyes. Here's the new shape of the book." +date: 2026-08-04 +automated: true +--- + +The third edition has a new shape. +The restructure just landed in the repository: chapters renumbered and retitled, two chapters that didn't exist before, and several that won't be coming back. +Let's walk through it. + +Here's the new table of contents: + +1. Getting Started +2. Git Basics +3. Git Branching +4. Distributed Git +5. Git Toolkit +6. Customizing Git +7. Git and Agents +8. Git Servers +9. Git at Scale +10. Git Internals + +…plus a single appendix, the Git command reference. + +## What's new + +Two chapters are brand new. + +**Git at Scale** (Chapter 9) is about what happens when your repository stops being small: shallow and partial clones, sparse checkout, Scalar, large files, and monorepo practice. +The second edition predates every one of those features, so this chapter starts from a blank page. +It sits second-to-last on purpose — it leans on the internals that Chapter 10 explains. + +**Git and Agents** (Chapter 7) is about using Git when some of your contributors are AI coding agents: workflows like branch-per-agent and worktree-per-agent, the tools and libraries agents drive Git with, and how to guide machine contributors in a repository you maintain. + +There are smaller additions too: + +- Git Branching finally gets a **Worktrees** section. `git worktree` has been in Git since 2.5, and the book has never mentioned it. +- Distributed Git gains a forge-neutral **Pull Requests and Forges** section — the fork-branch-PR loop, keeping a fork in sync, and what `refs/pull/*` actually is. +- Ignoring files grows from a passing subsection into a full section of Customizing Git. + +## What's gone + +The GitHub chapter is retired. +It was the fastest-aging part of the book — most of its screenshots stopped matching reality years ago — and its durable material (pull requests, forks, notifications) is exactly what the new forge-neutral section in Distributed Git now covers. +Account setup, organization management, and the API tour don't make the cut. + +Git and Other Systems is retired as well. +The Subversion, Mercurial, and Perforce bridges mattered when teams were migrating _to_ Git; that era is behind us, and the pages can go to material you'll actually use. + +Two of the three appendices go with them: the editor-and-GUI survey, and the embedding appendix — though the library survey from the latter resurfaces inside Git and Agents, updated with gitoxide and per-library SHA-256 notes. + +Two chapters change names along the way. +Git Tools is now **Git Toolkit**, and Git on the Server is now **Git Servers** — and it moves toward the back of the book, since most readers meet a hosted forge long before they run a server of their own. + +One thing to be clear about: what landed is the structure, not the writing. +The new chapters and sections are outline placeholders — notes on what each one will cover — and the prose will be [written by the book's human authors](../../authorship/), as all of it is. +The full section-by-section punch list is [`OUTLINE.md`](https://github.com/progit/progit3/blob/main/OUTLINE.md), and you can watch the boxes get ticked on the [progress page](../../blog/progress/). + +If you think the new shape is missing something, now is the time to say so — the outline is much easier to change than a finished chapter. +Open an issue at [github.com/progit/progit3](https://github.com/progit/progit3) and make the case.