e3517833
Update the README for OID-named revision refs
a73x 2026-08-09 19:29
Commit message
README.md
| Old | New | ||
|---|---|---|---|
| @@ -31,7 +31,7 @@ The part that is deliberately unlike a pull request. | |||
| 31 | 31 | ||
| 32 | A patch has numbered revisions. Comments anchor to the revision they were | 32 | A patch has numbered revisions. Comments anchor to the revision they were |
| 33 | written on, so they never drift onto lines that have since moved. When an author | 33 | written on, so they never drift onto lines that have since moved. When an author |
| 34 | rebases or amends, the next revision is recorded automatically, and you can diff | 34 | addresses review, `patch revise` records the next revision, and you can diff |
| 35 | revision against revision — an interdiff — to see exactly what the author | 35 | revision against revision — an interdiff — to see exactly what the author |
| 36 | changed in response to review, rather than re-reading the whole patch. | 36 | changed in response to review, rather than re-reading the whole patch. |
| 37 | 37 | ||
| @@ -41,9 +41,9 @@ $ git-collab patch diff a1b2c3d4 --between 1 2 # interdiff: what changed betwe | |||
| 41 | $ git-collab patch diff a1b2c3d4 --revision 2 # revision 2 against the base | 41 | $ git-collab patch diff a1b2c3d4 --revision 2 # revision 2 against the base |
| 42 | ``` | 42 | ``` |
| 43 | 43 | ||
| 44 | Each revision is an immutable ref in the patch's own namespace | 44 | Each revision is pinned by a ref in the patch's own namespace, named after the |
| 45 | (`refs/collab/patches/<id>/r/<n>`), so `git-collab sync` carries the patch and | 45 | commit it points at (`refs/collab/patches/<id>/rev/<oid>`), so `git-collab sync` |
| 46 | every revision it ever had. Contributing needs no `git push` of a branch and no | 46 | carries the patch and every revision it ever had. Contributing needs no `git push` of a branch and no |
| 47 | write access to `refs/heads/*`, and rebasing your branch cannot strip an earlier | 47 | write access to `refs/heads/*`, and rebasing your branch cannot strip an earlier |
| 48 | revision of the objects a reviewer is looking at. | 48 | revision of the objects a reviewer is looking at. |
| 49 | 49 | ||
| @@ -195,9 +195,10 @@ checksums, range requests and resumable downloads. | |||
| 195 | Everything lives in ordinary git objects. | 195 | Everything lives in ordinary git objects. |
| 196 | 196 | ||
| 197 | ``` | 197 | ``` |
| 198 | refs/collab/issues/<id> one commit per event, DAG-ordered | 198 | refs/collab/issues/<id> one commit per event, DAG-ordered |
| 199 | refs/collab/patches/<id> | 199 | refs/collab/patches/<id>/events the same, for a patch |
| 200 | refs/collab/archive/... closed items, kept out of the working set | 200 | refs/collab/patches/<id>/rev/<oid> pins a revision's commit so it survives a rebase |
| 201 | refs/collab/archive/... closed items, kept out of the working set | ||
| 201 | ``` | 202 | ``` |
| 202 | 203 | ||
| 203 | Each event commit's tree holds the event as canonical JSON alongside its | 204 | Each event commit's tree holds the event as canonical JSON alongside its |