Re: [RFC PATCH v7 0/10] diff: add provider interface and initial providers

> On 01/08/2026 18:41, Michael Montalbo wrote:
> > Every in-process diff in Git reduces, at one point, to a single
> > question: given two blobs and the settings the diff runs under, which
> > line ranges changed?  The answer is the diff's hunks: for each change,
> > the position and length of the range on the old side and on the new.
> > Each consumer asks in its own shape:
> >
> > - blame diffs each suspect's blob against its parent's, taking only the
> >    coordinates through xdiff's hunk callback;
> > - the stat formats keep only the added and deleted counts;
> > - patch output emits from the hunks, with xdiff interleaving context and
> >    content around them;
> > - log -L maps the tracked range across each commit from the coordinates.
> >
> > In every case the answer is computed the same way: load both blobs and
> > run xdiff.  That is the only source, so nothing that already holds the
> > answer, or that would answer differently on purpose, can supply it
> > instead.  Sometimes that is what we want, which is why patch-id and
> > format-patch stay on the builtin computation throughout: patch-id needs
> > identical hashes on every machine, and a format-patch must apply for
> > recipients who share none of the sender's configuration.  Other times
> > another source would be useful.
>
> This explains the mechanics of the existing implementation, but doesn't
> really explain what the advantage of the change is beyond having a
> unified interface. What are things that are unlocked by this change? Are
> we doing it purely to cache the hunk headers or does it (as I suspect)
> unlock other features?
>

> > This RFC sketches a direction.  The unified series shows one interface
> > carrying two example providers and their interaction; it is not shaped
> > to merge as one topic.  If the direction holds, the work returns as
> > separate reviewable series (see Roadmap).  The two examples are
> > demonstrations, each an RFC on its own: diff.<driver>.process, the RFC
> > cooking as mm/diff-process-hunks, lets a configured external process
> > answer with its own notion of which lines changed, and the diff-hunks
> > store, new in this thread, remembers what xdiff computed and serves it
> > back.  One is authoritative and external, one a cache and in-process.
>
> What does it mean to be authoritative? Why isn't the xdiff code
> authoritative?
>

> >    terminal provider is the builtin computation itself, so the interface
> >    never exists without an implementor: patch 02 ships it answering every
> >    request the way the consumers did before.  A consumer states its
> >    request in one struct and reads one set of outcomes (answered,
> >    unanswered, or failed); it never names a provider, and a provider>    added later maps onto those outcomes inside the interface, so consumer
> >    code is written once.  Because every diff now walks the chain even
> >    with no store or process configured, the default path was measured
> >    against the pre-series base and runs within noise (a 5000-commit
> >    log --stat and a long-history blame, ratio 1.00 either way).
>
> So we can configure a provider for a particular file type via
> .gitattributes and diff.<driver>.process and then it is used
> automatically, if there is no provider configured we use xdiff?
>

> > - The diff-hunks store shows the non-authoritative side: an in-process
> >    cache at $GIT_DIR/objects/info/diff-hunks that may only reproduce the
> >    builtin diff, so serving from it never changes a command's output.  It
> >    is read by default and written only when a repository owner opts in,
> >    warming it as a side effect of diff work the command already does:
> >
> >        GIT_DIFF_HUNKS_WRITE=1 git log --all --stat >/dev/null
> >
> >    A warmed store then serves the stat formats and blame from stored
> >    coordinates instead of a fresh diff: on git.git a 5000-commit log
> >    --stat runs about 1.9x faster, and blame reads the same entries
> >    opportunistically (full numbers in [1]).  Its format and keying, what
> >    it may not serve, and how it handles corruption and staleness are in
> >    git-diff-hunks(1), gitformat-diff-hunks(5), and [2].  The interface
> >    point is small: a cache drops in as the provider that stands aside
> >    wherever an authoritative one answers.
>
> I had a very quick look at the documentation in patch that implements
> this. Am I right in thinking it stores xdl_opts directly so that we
> cannot change the in-memory representation without breaking the cache?
> Are there plans to garbage collect cache entries when the corresponding
> blobs are removed?
>

> > - diff.<driver>.process shows the authoritative side: an external
> >    process, configured per driver, whose answers may deliberately differ
> >    from the builtin diff and outrank the store.  Git asks it for a pair by
> >    object names alone, so it answers before any blob is read, which suits
> >    a cache or a process that fetches the blobs itself.  Consulting is
> >    opt-in per command, following the allow_textconv precedent, and a pair
> >    the process cannot answer falls back to the builtin diff.  The
> >    protocol, the per-command gate, how failures are handled, and the
> >    versioning that lets it grow are in gitattributes(5) and footnotes [3]
> >    and [4].  The interface point, again, is small: an external,
> >    authoritative provider joins the same chain ahead of the cache, and
> >    neither consumer learns it is there.  A later content-carrying request
> >    would extend it to the pairs and consumers this identity-only form
> >    leaves on the builtin diff.
> >
> > The series stops at the coordinates.
>
> Does this mean the offsets and lengths in the hunk header? I can't see
> any reference to "coordinates" in the existing code.
>

> > A consumer that needs the changed
> > text, such as patch output, would have only its hunk selection replaced,
> > with xdiff still emitting content from the blobs; that machinery is the
> > content enrichment sketched in the Roadmap.  Establishing the framework
> > on coordinates first keeps this series one design: the question, the
> > interface, and two providers answering by identity.
>
> This seems like an interesting proposal and the diff headers seem like a
> good place for initial phase to stop. It would be helpful to have a
> clearer explanation of the features this interface would support (i.e.
> what's the motivation for these changes) and a lot less jargon in the
> interface description.
>