docs tweaks and touchups.
commit f7d299ab1981ea08451d306bf50e697ec3b2a165 · parent f4a2518b27
· browse this tree
warpfork, 2026-10-27 13:58:26 UTC
diff --git a/README.md b/README.md index 9054de4..354b078 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,17 @@ indeed, git and git-rebase are already fundamentally storing patches and helping but things don't handle that last bit: tracking the evolution. +Usage +----- + +**Head over to [docs/userguide/USAGE.md](docs/userguide/USAGE.md).** + +There you'll find both the full usage flow shown, +and examples of the structure of the patch files generated. + +For guts? Check out [docs/hacking/](docs/hacking/). + + The Bigger Picture ------------------ diff --git a/docs/userguide/USAGE.md b/docs/userguide/USAGE.md index 79abaa1..cae1f89 100644 --- a/docs/userguide/USAGE.md +++ b/docs/userguide/USAGE.md @@ -40,7 +40,12 @@ The sessions in the rest of this guide each start as though you'd just done that Taking snapshots ---------------- -Work on your branches however you like; then export them, and commit the result in the patches repo. +Work on your branches however you like; +then export them with the `patchette export` command, +and (presumably, if you want history over your patches) commit the result in the patches repo. + +Here we've got a repo where we have two branches with a handful of commits each that we're going to export. + Export takes the upstream commit your branches are based on, then the branches: [testmark]:# (snapshot/session) @@ -59,10 +64,15 @@ polish-the-readme.patch ~/src/frob$ git -C ../frob-patches commit -q -m "first snapshot" ``` -Each branch becomes a folder: a `STACK` file saying where it's based and what's in it, and one patch file per commit. +Each branch becomes a folder, containing +a `STACK` file outlining the branch, what it's based on, and what's in it; +and one patch file per commit. + +### the files + +Here's a quick peak into the files produced by the export: -`~/src/frob-patches/docs-polish/STACK` names the branch, the upstream commit it's based on, and its tip; -then, after `series`, its patches, in order: +First, here's `~/src/frob-patches/docs-polish/STACK`: [testmark]:# (snapshot/STACK) ``` @@ -74,8 +84,14 @@ polish-the-readme mention-the-oiling-schedule ``` +It names the branch, the upstream commit it's based on, and its tip; +then, after `series`, its patches, in order. + `~/src/frob-patches/docs-polish/polish-the-readme.patch` is one commit: -its parents (`BASE` is the STACK's base), then the rest of its headers exactly as git stored them; its message, between `----` lines; and its diff: +its parents (`BASE` is the STACK's base), +then the rest of its headers exactly as git stored them; +then the commit message, marked by flanking `----` lines and with `>` prefixes; +and everything after that is finally the diff itself: [testmark]:# (snapshot/polish-the-readme.patch) ``` @@ -101,6 +117,8 @@ index a330cd687e7fdede54bbe0aca5df47c06d2e8b64..c195933372242cdbb3c014665ebcff2b Both formats are specified in full in [FORMAT.md](../hacking/FORMAT.md). +### change over time + The payoff comes when your patches change. Here, a commit on `docs-polish` gets reworked; export again, and the patches repo shows what changed about the change: @@ -168,9 +186,17 @@ Commit that with a message saying why it changed, and the history of your patche Checking a snapshot ------------------- -`verify` rebuilds each branch from its patches, off to the side, and checks it comes out exactly as it was recorded. -It never touches your branches. -Name branches to check just those: +`patchette verify` runs a reconstruction of each branch from its patches +(without actually modifying the git repo!), +and checks it comes out exactly as it was recorded. + +Useful for the paranoid and cautious, effectively. +But also can tell you if you've edited the patches manually (see more about this in the next section) +and have forgotten to regenerated any of the logged hashes. + +One can also name specific branches to check just those. + +Usage looks like this: [testmark]:# (paired/verifying/session) ``` @@ -186,11 +212,13 @@ verify: ok: refs/heads/topic/fancy reproduces recorded tip cc261dc9f0b878a78e2b8 verify: ok: refs/heads/topic/fancy reproduces recorded tip cc261dc9f0b878a78e2b80aeb60de397205f61ad ``` +(See `patchette import`, in the next section, if you want to actually have an effect rather than just check.) + Rebuilding branches in a fresh clone ------------------------------------ -The patches repo is enough to bring your branches back, exactly, in a clone that never had them. +`patchette import` can rebuild your branches, exactly, in a clone that never had them. Pair the new clone, and import: [testmark]:# (paired/recreating/session) @@ -219,14 +247,21 @@ cc261dc9f0b878a78e2b80aeb60de397205f61ad cc261dc9f0b878a78e2b80aeb60de397205f61ad ``` +(This is the same thing as `patchette verify`, but actually... having an effect.) + Editing patches by hand ----------------------- -Patch files are plain text, and fine to edit directly. -Then rebuild the branch from them. -`import` won't replace a branch that already exists unless you say `-f`, -and even then, not the branch you have checked out: switch away first. +Patch files are plain text, and *can be edited directly*, if desired! +Branches in the repo can then be rebuilt from the (changed) patches -- +this is kinda like an interactive rebase process on steroids. + +(Do mind, however, that `patchette import` won't replace a branch that already exists unless you say `-f`, +for some safety against accidents. +And for reasons of git's norms, it also won't apply an import to the branch you have checked out: switch away first.) + +Using Patchette and editing patches to change history looks like this: [testmark]:# (paired/hand-editing/session) ``` @@ -263,8 +298,11 @@ export: wrote ~/src/frob-patches/topic¦fancy (8 patches) verify: ok: refs/heads/topic/fancy reproduces recorded tip 57d05b16d9ad81fd92af19d210f0884dc9745e01 ``` -`verify` fails right after the edit: the patches no longer match the snapshot they were taken as. -Exporting the rebuilt branch takes a new snapshot of it, and they agree again. +Note that `patchette verify` fails right after the manual edits: +this makes sense, because if the patches have been changed, of course they no longer produce +the exact same resulting history and content in git, so they expected tip hash has to be updated. +A `patchette import -f` and `patchette export` round trip will cause the tip hash to be freshly recorded +and result in a happy verify again. Without pairing @@ -289,6 +327,9 @@ verify: ok: refs/heads/docs-polish reproduces recorded tip 2dfecf1d7ce26028ef2dc When something's wrong ---------------------- +... then Patchette will still try to give reasonable error messages and guidance. +Here's some of those cases on display: + [testmark]:# (fresh/refusals/session) ``` ~$ cd src/frob