Skip to content

progress.asc

Latest commit

 

History

History
172 lines (131 loc) · 8.63 KB

progress.asc

File metadata and controls

172 lines (131 loc) · 8.63 KB
Raw

Pro Git, 3rd Edition — Progress

Table of Contents

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

  • ✓ Import the 2nd-edition sources as the starting point

  • ✓ Write the revision plan (REVISION_PLAN.md)

  • ✓ Build the line-level master → main inventory (book_master_to_main_inventory.md)

  • ✓ Launch the project site — book reader, blog, history

  • ✓ Set up the cloud build/test environment for agents

  • ✓ Link ebook downloads (PDF/EPUB/FB2/HTML) from the site’s book page

  • ✓ Switch the PDF code font to JetBrains Mono

Restructure

  • ✓ Write the full chapter/section outline and punch list (OUTLINE.md)

  • ✓ Renumber and retitle the chapters (Git Toolkit, Git Servers, new order)

  • ✓ Create the new placeholder chapters — Git and Agents (Ch 7), Git at Scale (Ch 9)

  • ✓ Create the new placeholder sections — Worktrees (3.5), Pull Requests and Forges (4.3), Ignoring Files (6.2)

  • ✓ Drop the GitHub chapter, Git and Other Systems, and the environments/embedding appendices; keep the command reference as Appendix A

  • ✓ Retarget every cross-reference; render xrefs as chapter labels instead of filenames

Policy decisions

These gate the cross-cutting sweeps; decide them first.

  • ❏ Decide the master → main rename policy (gates X1, ~602 renames)

  • ❏ Decide how to represent example hashes: regenerate everything at SHA-256, or keep labeled SHA-1 legacy examples (gates X2)

Cross-cutting sweeps

Numbered as in OUTLINE.md.

  • ❏ X1 — master → main across the book (see the inventory for the per-line breakdown)

  • ❏ 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 — restructure plumbing: include map, chapter renumbering, placeholders, drops

  • ✓ 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

  • ❏ Update the headline SHA-1 passage in what-is-git.asc (X2)

  • ❏ Refresh per-platform install steps in installing.asc

  • ❏ 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

  • ❏ 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

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 — Distributed Git

  • ❏ X1 sweep (contributing 48 renames, maintaining 39)

  • ❏ 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)

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

  • ❏ 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 6 — Customizing Git

  • ❏ 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

  • ❏ 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 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.

  • ❏ 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; redo the big-file removal example with filter-repo

  • ❏ Add commit-graph and multi-pack-index format coverage

  • ❏ X1 sweep (70 renames)

Appendix A — Git Commands

  • ❏ 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 — decide where it lives, then write it

Publication

  • ❏ Redo the contributors list and dedication

  • ❏ 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