git/Documentation/Makefile, branch main

Merge branch 'en/xdiff-cleanup-2'

2025-12-05T05:49:56Z

Code clean-up. * en/xdiff-cleanup-2: xdiff: rename rindex -> reference_index xdiff: change rindex from long to size_t in xdfile_t xdiff: make xdfile_t.nreff a size_t instead of long xdiff: make xdfile_t.nrec a size_t instead of long xdiff: split xrecord_t.ha into line_hash and minimal_perfect_hash xdiff: use unambiguous types in xdl_hash_record() xdiff: use size_t for xrecord_t.size xdiff: make xrecord_t.ptr a uint8_t instead of char xdiff: use ptrdiff_t for dstart/dend doc: define unambiguous type mappings across C and Rust

Merge branch 'je/doc-data-model'

2025-12-01T02:31:40Z

Add a new manual that describes the data model. * je/doc-data-model: doc: add an explanation of Git's data model

doc: define unambiguous type mappings across C and Rust

2025-11-18T22:53:09Z

Document other nuances when crossing the FFI boundary. Other language mappings may be added in the future. Signed-off-by: Ezekiel Newren Signed-off-by: Junio C Hamano

doc: add an explanation of Git's data model

2025-11-12T20:21:15Z

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: 1. `gitglossary`. This makes a good effort, but it's an alphabetically ordered dictionary and a dictionary is not a good way to learn concepts. You have to jump around too much and it's not possible to present the concepts in the order that they should be explained. 2. `gitcore-tutorial`. This explains how to use the "core" Git commands. This is a nice document to have, but it's not necessary to learn how `update-index` works to understand Git's data model, and we should not be requiring users to learn how to use the "plumbing" commands if they want to learn what the term "index" or "object" means. 3. `gitrepository-layout`. This is a great resource, but it includes a lot of information about configuration and internal implementation details which are not related to the data model. It also does not explain how commits work. The result of this is that Git users (even users who have been using Git for 15+ years) struggle to read the documentation because they don't know what the core terms mean, and it's not possible to add links to help them learn more. Add an explanation of Git's data model. Some choices I've made in deciding what "core data model" means: 1. Omit pseudorefs like `FETCH_HEAD`, because it's not clear to me if those are intended to be user facing or if they're more like internal implementation details. 2. Don't talk about submodules other than by mentioning how they relate to trees. This is because Git has a lot of special features, and explaining how they all work exhaustively could quickly go down a rabbit hole which would make this document less useful for understanding Git's core behaviour. 3. Don't discuss the structure of a commit message (first line, trailers etc). 4. Don't mention configuration. 5. Don't mention the `.git` directory, to avoid getting too much into implementation details Signed-off-by: Julia Evans Signed-off-by: Junio C Hamano

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