git/Documentation/Makefile, branch v2.52.0

Merge branch 'rj/doc-technical-fixes'

2025-10-24T20:48:04Z

Documentation mark-up fixes. * rj/doc-technical-fixes: doc: add large-object-promisors.adoc to the docs build doc: commit-graph.adoc: fix up some formatting doc: sparse-checkout.adoc: fix asciidoc warnings doc: remembering-renames.adoc: fix asciidoc warnings

Merge branch 'bc/sha1-256-interop-01'

2025-10-22T18:38:58Z

The beginning of SHA1-SHA256 interoperability work. * bc/sha1-256-interop-01: t1010: use BROKEN_OBJECTS prerequisite t: allow specifying compatibility hash fsck: consider gpgsig headers expected in tags rev-parse: allow printing compatibility hash docs: add documentation for loose objects docs: improve ambiguous areas of pack format documentation docs: reflect actual double signature for tags docs: update offset order for pack index v3 docs: update pack index v3 format

doc: add large-object-promisors.adoc to the docs build

2025-10-16T20:55:53Z

Commit 5040f9f164 ("doc: add technical design doc for large object promisors", 2025-02-18) added the large object promisors document as a technical document (with a '.txt' extension). The merge commit 2c6fd30198 ("Merge branch 'cc/lop-remote'", 2025-03-05) seems to have renamed the file with an '.adoc' extension. Despite the '.adoc' extension, this document was not being formatted by asciidoc(tor) as part of the docs build. In order to do so, add the document to the make and meson build files. Having added the document to the build, asciidoc and asciidoctor find (slightly different) problems with the syntax of the input document. The first set of warnings (only issued by asciidoc) relate to some 'section title out of sequence: expected level 3, got level 4'. This document uses 'setext' style of section headers, using a series of underline characters, where the character used denotes the level of the title. From document title to level 5 (see [1]), these characters are =, -, ~, ^, +. This does not seem to fit the error message, which implies that those characters denote levels 0 -> 4. Replacing the headings underlined with '+' by the '^' character eliminates these warnings. The second set of warnings (only issued by asciidoctor) relate to some headings which seem to use both arabic and roman numerals as part of a single 'list' sequence. This elicited either 'unterminated listing block' or (for example) 'list item index: expected I, got II' warnings. In order not to mix arabic and roman numerals, remove the numeral from the '0) Non goals' heading. Similarly, the remaining roman numeral entries had the ')' removed and turned into regular headings with I, II, III ... at the beginning. [1] https://asciidoctor.org/docs/asciidoc-recommended-practices/ Signed-off-by: Ramsay Jones Signed-off-by: Junio C Hamano

docs: add documentation for loose objects

2025-10-10T00:46:14Z

We currently have no documentation for how loose objects are stored. Let's add some here so it's easy for people to understand how they work. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano

doc: add some missing technical documents

2025-10-03T16:44:01Z

Commit bcf7edee09 ("meson: generate articles", 2024-12-27) added the generation of the 'howto' and 'technical' documents to the meson build. At this time those documents had a '*.txt' file extension, but they were renamed with an '*.adoc' extension by commit 1f010d6bdf ("doc: use .adoc extension for AsciiDoc files", 2025-01-20), for the most part. For the meson build, commit 87eccc3a81 ("meson: fix building technical and howto docs", 2025-03-02) fixed the meson.build files, which had not been updated when the files were renamed. However, the 'Documentation/Makefile' has not been updated to include all of the recently added technical documents. In particular, the following are built by meson, but not by the Makefile: commit-graph.adoc directory-rename-detection.adoc packfile-uri.adoc remembering-renames.adoc repository-version.adoc rerere.adoc sparse-checkout.adoc sparse-index.adoc In order to ensure that both build systems format the same technical documents, add the above documents to the TECH_DOCS variable in the Documentation/Makefile. Signed-off-by: Ramsay Jones Signed-off-by: Junio C Hamano

doc: check for absence of multiple terms in each entry of desc list

2025-08-11T21:16:04Z

For simplifying automated translation of the documentation, it is better to only present one term in each entry of a description list of options. This is because most of these terms can automatically be marked as notranslatable. Also, due to portability issues, the script generate-configlist.sh can no longer insert newlines in the output. However, the result is that it no longer correctly handles multiple terms in a single entry of definition lists. As a result, we now check that these entries do not exist in the documentation. Reviewed-by: Collin Funk Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano

doc: check well-formedness of delimited sections

2025-08-11T21:16:03Z

Having an empty line before each delimited sections is not required by asciidoc, but it is a safety measure that prevents generating malformed asciidoc when generating translated documentation. When a delimited section appears just after a paragraph, the asciidoc processor checks that the length of the delimited section header is different from the length of the paragraph. If it is not, the asciidoc processor will generate a title. In the original English documentation, this is not a problem because the authors always check the output of the asciidoc processor and fix the length of the delimited section header if it turns out to be the same as the paragraph length. However, this is not the case for translations, where the authors have no way to check the length of the delimited section header or the output of the asciidoc processor. This can lead to a section title that is not intended. Indeed, this test also checks that titles are correctly formed, that is, the length of the underline is equal to the length of the title (otherwise it would not be a title but a section header). Finally, this test checks that the delimited section are terminated within the same file. Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano

Merge branch 'jc/you-still-use-whatchanged'

2025-06-25T21:07:35Z

"git whatchanged" that is longer to type than "git log --raw" which is its modern rough equivalent has outlived its usefulness more than 10 years ago. Plan to deprecate and remove it. * jc/you-still-use-whatchanged: whatschanged: list it in BreakingChanges document whatchanged: remove when built with WITH_BREAKING_CHANGES whatchanged: require --i-still-use-this tests: prepare for a world without whatchanged doc: prepare for a world without whatchanged you-still-use-that??: help deprecating commands for removal

Documentation: stop depending on Perl to generate command list

2025-04-16T14:30:30Z

The "cmd-list.perl" script is used to extract the list of commands part of a specific category and extracts the description of each command from its respective manpage. The generated output is then included in git(1) to list all Git commands. The script is written in Perl. Refactor it to use shell scripting exclusively so that we can get rid of the mandatory dependency on Perl to build our documentation. The converted script is slower compared to its Perl implementation. But by being careful and not spawning external commands in `format_one ()` we can mitigate the performance hit to a reasonable level: Benchmark 1: Perl Time (mean ± σ): 10.3 ms ± 0.2 ms [User: 7.0 ms, System: 3.3 ms] Range (min … max): 10.0 ms … 11.1 ms 200 runs Benchmark 2: Shell Time (mean ± σ): 74.4 ms ± 0.4 ms [User: 48.6 ms, System: 24.7 ms] Range (min … max): 73.1 ms … 75.5 ms 200 runs Summary Perl ran 7.23 ± 0.13 times faster than Shell While a sevenfold slowdown is significant, the benefit of not requiring Perl for a fully-functioning Git installation outweighs waiting a couple of milliseconds longer during the build process. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano

Documentation: stop depending on Perl to massage user manual

2025-04-16T14:30:29Z

The "fix-texi.perl" script is used to fix up the output of `docbook2x-texi`: - It changes the filename to be "git.info". - It changes the directory category and entry. The script is written in Perl, but it can be rather trivially converted to a shell script. Do so to remove the dependency on Perl for building the user manual. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano