From: Kristofer Karlsson Date: Thu, 15 Oct 2026 09:12:50 GMT Subject: Re: [PATCH v3 1/4] Documentation: describe connectivity checking Message-ID: In-Reply-To: On Thu, 15 Oct 2026 at 08:55, Patrick Steinhardt wrote: > > 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? Ah yes, will fix for next reroll. > > > 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? Hm perhaps. Or I can remove it instead, I think it depends on how detailed we want this to be. I will take a deeper look at this. > > +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". Agreed, I think that would be easier to read. Will fix. Thanks, Kristofer