From: Patrick Steinhardt Date: Thu, 15 Oct 2026 06:55:20 GMT Subject: Re: [PATCH v3 1/4] Documentation: describe connectivity checking Message-ID: In-Reply-To: <19ea8cb534f0aaabdf21f358364ad32295b6bfc8.1791806877.git.gitgitgadget@gmail.com> On Mon, Oct 12, 2026 at 12:07:54PM +0000, Kristofer Karlsson via GitGitGadget wrote: > From: Kristofer Karlsson > > Add Documentation/technical/connectivity-check.adoc describing > the connectivity invariant and the full connectivity check. > > Signed-off-by: Kristofer Karlsson > --- > .../technical/connectivity-check.adoc | 110 ++++++++++++++++++ > 1 file changed, 110 insertions(+) > create mode 100644 Documentation/technical/connectivity-check.adoc Shouldn't both the Makefile (`TECH_DOCS`) and Meson (`articles`) be adapted to build this? > diff --git a/Documentation/technical/connectivity-check.adoc b/Documentation/technical/connectivity-check.adoc > new file mode 100644 > index 0000000000..abef02debd > --- /dev/null > +++ b/Documentation/technical/connectivity-check.adoc [snip] > +Full connectivity check > +----------------------- > + > +The full connectivity check runs a `rev-list` subprocess, feeding > +the new reference tips via stdin. A normal invocation is roughly: > + > + git rev-list --objects --stdin --not --all --quiet > + --alternate-refs [--exclude-promisor-objects] > + > +When promisor remotes are configured, a fast path based on > +promisor packfiles is attempted first. If it falls back to > +the `rev-list` check, `--exclude-promisor-objects` is added so > +that the traversal does not trigger on-demand fetches. Would it make sense to document that fast path here, too? > +Consider the following graph after a fetch, where all reference > +tips point directly to commits. For simplicity, only local > +references appear on the already-connected side; alternate refs > +play the same role. N3 is a merge commit: > + > + /-------------L2 > + / > + C1---B1---C2---B2-----L1 > + \ \ > + N1 N3---T2 > + \ / > + N2-----------T1 > + > + L1, L2: local refs > + T1, T2: incoming tips (new refs) > + N1, N2, N3: incoming commits (N3 is a merge) > + B1, B2: boundary commits (already connected) > + C1, C2: already connected (but not boundary) > + > +The incoming set is the commits reachable from the incoming > +tips but not from the already-connected side. Boundary commits > +are the already-connected commits at the edge of that set. Here > +B1 is an ancestor of B2, which happens when incoming branches > +fork at different depths in the existing history. > + > +The `--not --all` arguments establish the trust boundary: the > +incoming set is the commits reachable from the new tips but not > +from any existing reference. > + > +The traversal then walks the trees of the boundary commits and > +marks those objects uninteresting. Trees of incoming commits > +are verified against these marks, stopping at objects already Nit: "verified against these marks" reads a tiny bit awkward. How about "Trees of incoming commits are then walked, stopping at objects already marked as uninteresting". > +covered. The cost of marking boundary trees uninteresting > +dominates when the boundary commits have large trees, even when > +the incoming changes are small. Overall I think this part is a lot better now, thanks. Patrick