Re: [PATCH v3] doc: add a explanation of Git's data model

From: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date: Oct 20, 2025, 16:37 UTC
Message-ID: <c1c456b5-aca7-4b24-a4a2-558405214f24@app.fastmail.com>
In-Reply-To: <pull.1981.v3.git.1760476346040.gitgitgadget@gmail.com>

On Tue, Oct 14, 2025, at 23:12, Julia Evans via GitGitGadget wrote:

Show 9 quoted lines

> From: Julia Evans <julia@jvns.ca>
>
> Git very often uses the terms "object", "reference", or "index" in its
> documentation.
>
> However, it's hard to find a clear explanation of these terms and how
> they relate to each other in the documentation. The closest candidates
> currently are:
>[snip]

For some reason I get an error with `Documentation/doc-diff` when run against 446c8a72 (Merge branch 'je/doc-data-model' into seen, 2025-10-16). Here I’m comparing with `master`.

    $ ./doc-diff 4253630c6f07a4bdcc9aa62a50e26a4d466219d1 446c8a72be6cf1b6121e643590a9acacfc21c5fb
    Previous HEAD position was b20e48e0232 doc: add a explanation of Git's data model
    HEAD is now at 446c8a72be6 Merge branch 'je/doc-data-model' into seen
    make: Entering directory '<git repo>/Documentation/tmp-doc-diff/worktree'
    install -d -m 755 '<git repo>/Documentation/tmp-doc-diff/installed/446c8a72be6cf1b6121e643590a9acacfc21c5fb+/home/kristoffer/share/man/man3'
    (cd perl/build/man/man3 && tar cf - .) | \
    (cd '<git repo>/Documentation/tmp-doc-diff/installed/446c8a72be6cf1b6121e643590a9acacfc21c5fb+/home/kristoffer/share/man/man3' && umask 022 && tar xof -)
    make -C Documentation install-man
    make[1]: Entering directory '<git repo>/Documentation/tmp-doc-diff/worktree/Documentation'
        GEN cmd-list.made
        GEN doc.dep
        GEN asciidoc.conf
        ASCIIDOC git-add.xml
        ASCIIDOC git-config.xml
        ASCIIDOC git-diff-tree.xml
        ASCIIDOC git-fast-import.xml
        ASCIIDOC git-fetch.xml
        ASCIIDOC git-fsck.xml
        ASCIIDOC git-log.xml
        ASCIIDOC git-merge-tree.xml
        ASCIIDOC git-patch-id.xml
        ASCIIDOC git-pull.xml
        ASCIIDOC git-push.xml
        ASCIIDOC git-replay.xml
        ASCIIDOC git-repo.xml
        ASCIIDOC git-rev-list.xml
        ASCIIDOC git-rev-parse.xml
        ASCIIDOC git-shortlog.xml
        ASCIIDOC git-show.xml
        ASCIIDOC git-sparse-checkout.xml
        ASCIIDOC git-stash.xml
        ASCIIDOC git-tag.xml
        ASCIIDOC git-worktree.xml
        ASCIIDOC git.xml
        ASCIIDOC gitformat-loose.xml
        ASCIIDOC gitformat-pack.xml
        ASCIIDOC gitcli.xml
        ASCIIDOC gitcredentials.xml
        XMLTO gitdatamodel.7
        XMLTO git-add.1
        XMLTO git-diff-tree.1
        XMLTO git-fast-import.1
        XMLTO git-fetch.1
        XMLTO git-fsck.1
    xmlto: <git repo>/Documentation/tmp-doc-diff/worktree/Documentation/gitdatamodel.xml does not validate (status 3)
    xmlto: Fix document syntax or use --skip-validation option
    <git repo>/Documentation/tmp-doc-diff/worktree/Documentation/gitdatamodel.xml:71: element link: validity error : IDREF attribute linkend references an unknown ID "tree"
    <git repo>/Documentation/tmp-doc-diff/worktree/Documentation/gitdatamodel.xml:96: element link: validity error : IDREF attribute linkend references an unknown ID "tree"
    <git repo>/Documentation/tmp-doc-diff/worktree/Documentation/gitdatamodel.xml:397: element link: validity error : IDREF attribute linkend references an unknown ID "tree"
    Document <git repo>/Documentation/tmp-doc-diff/worktree/Documentation/gitdatamodel.xml does not validate
    make[1]: *** [Makefile:380: gitdatamodel.7] Error 13
    make[1]: *** Waiting for unfinished jobs....
    make[1]: Leaving directory '<git repo>/Documentation/tmp-doc-diff/worktree/Documentation'
    make: *** [Makefile:3676: install-man] Error 2
    make: Leaving directory '<git repo>/Documentation/tmp-doc-diff/worktree'

The syntax looks correct. So I don’t know what is wrong. `make html` works *and* makes the link.

At first look it might be to do with the anchor on a definition list but I tried removing the anchors and expected to get an error for `blob` next. But that didn’t happen.

In short I don’t see what is special about `tree`.