diff --git a/book/preface.asc b/book/preface.asc new file mode 100644 index 0000000..96c1ae5 --- /dev/null +++ b/book/preface.asc @@ -0,0 +1,35 @@ +[preface] +== Preface to the Third Edition + +//// +AUTHOR TODO: outline notes only — the actual preface prose must be written by a +human author before publication (see AGENTS.md). Replace everything below with +real prose. +//// + +[NOTE] +==== +*Draft placeholder — outline notes only; prose not yet written.* +==== + +Points this preface needs to make: + +* *Timing*: edition written _before_ the Git 3.0 release +** based on the announced/committed 3.0 breaking changes (see the + https://git-scm.com/docs/BreakingChanges[BreakingChanges document]) +** no firm 3.0 release date at time of writing; details could still shift +* *Stance*: the book treats the *new 3.0 defaults as the defaults* throughout +** `main` as the default branch name +** SHA-256 as the default object hash for new repositories +** `reftable` as the default ref storage backend +** `safe.bareRepository` = `explicit` +* *Dual paths*: some sections deliberately cover *both* the old and new behavior, + because readers will live with both for years +** SHA-1 vs SHA-256 (existing repos stay SHA-1; interop story) +** `files`/packed-refs vs `reftable` ref storage +** `master`-named branches in older/existing repositories +* *Readers on Git 2.x*: what to expect if their installed Git predates 3.0 + (which defaults differ, how to opt in early — e.g. `init.defaultBranch`, + `--object-format`) +* *Caveat*: commands still marked experimental at time of writing + (e.g. `git history`) may change by/after 3.0 diff --git a/progit.asc b/progit.asc index 65cce16..947c6d1 100644 --- a/progit.asc +++ b/progit.asc @@ -10,6 +10,8 @@ Scott Chacon; Ben Straub include::book/license.asc[] +include::book/preface.asc[] + include::book/introduction.asc[] include::book/ch01-getting-started.asc[]