Skip to content

Update progress.asc to the new outline; add a blog post on the new table of contents #22

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
schacon merged 2 commits into from
Aug 4, 2026
+154 −53
Merged

Update progress.asc to the new outline; add a blog post on the new table of contents #22

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c664c69
Update progress.asc to the new outline and chapter numbering
cursoragent Aug 4, 2026
bfeaae5
Add blog post on the third edition's new table of contents
cursoragent Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 92 additions & 53 deletions progress.asc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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

Expand All @@ -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

Expand All @@ -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
62 changes: 62 additions & 0 deletions site/src/content/blog/a-new-table-of-contents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.