From: Junio C Hamano Date: Mon, 20 Oct 2025 18:01:32 GMT Subject: Re: [PATCH v3] doc: add a explanation of Git's data model Message-ID: In-Reply-To: "Kristoffer Haugsbakk" writes: > xmlto: /Documentation/tmp-doc-diff/worktree/Documentation/gitdatamodel.xml does not validate (status 3) > xmlto: Fix document syntax or use --skip-validation option > /Documentation/tmp-doc-diff/worktree/Documentation/gitdatamodel.xml:71: element link: validity error : IDREF attribute linkend references an unknown ID "tree" > /Documentation/tmp-doc-diff/worktree/Documentation/gitdatamodel.xml:96: element link: validity error : IDREF attribute linkend references an unknown ID "tree" > /Documentation/tmp-doc-diff/worktree/Documentation/gitdatamodel.xml:397: element link: validity error : IDREF attribute linkend references an unknown ID "tree" > Document /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 '/Documentation/tmp-doc-diff/worktree/Documentation' > make: *** [Makefile:3676: install-man] Error 2 > make: Leaving directory '/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`. This seems to work it around without breaking .html generation too badly for AsciiDoc and without breaking .7/.html generation for Asciidoctor. Generation of .7 were broken with AsciiDoc so we cannot complain even if the result is suboptimal, but the generated manpage with this patch using AsciiDoc did not look too bad, either. I do not know AsciiDoc internals (and I am not particularly interested to learn it now), but I am guessing that the bug is that when it sees [[tree]], it tries to find an element to put id="tree", but before it finds any approprifate one, it sees [[filemode]] and uses the element it finds to hold id="filemode", losing sight of the need to add id="tree" somewhere. Documentation/gitdatamodel.adoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Documentation/gitdatamodel.adoc b/Documentation/gitdatamodel.adoc index f49574dfae..7232fe3861 100644 --- a/Documentation/gitdatamodel.adoc +++ b/Documentation/gitdatamodel.adoc @@ -83,8 +83,10 @@ trees:: A tree is how Git represents a directory. It lists, for each item in the tree: + +1. The *file mode*, for example `100644`. ++ [[file-mode]] -1. The *file mode*, for example `100644`. The format is inspired by Unix +The format is inspired by Unix permissions, but Git's modes are much more limited. Git only supports these file modes: + - `100644`: regular file (with type `blob`) -- 2.51.1-556-g06b2a500e9