From c035be5d54573bc8dfcbef3ab66de88f2adce7db Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Sun, 23 Aug 2026 13:32:46 +0200 Subject: [PATCH 1/4] doc: git: list gitdatamodel(7) as a concept guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit dee80940 (doc: add an explanation of Git's data model, 2025-11-12) added gitdatamodel(7), documenting Git’s data model. But it is not mentioned anywhere. Let’s start by listing it under Guides in git(1) and with `git help --guides`. Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano --- command-list.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/command-list.txt b/command-list.txt index 21b802c420..63ae2a67c9 100644 --- a/command-list.txt +++ b/command-list.txt @@ -217,6 +217,7 @@ gitcli userinterfaces gitcore-tutorial guide gitcredentials guide gitcvs-migration guide +gitdatamodel guide gitdiffcore guide giteveryday guide gitfaq guide From 3e13dd44e81f344a74173d8e7726a27fb79b2058 Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Sun, 23 Aug 2026 13:32:47 +0200 Subject: [PATCH 2/4] doc: git: link to the gitdatamodel(7) tutorial MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous commit added the first mention of gitdatamodel(7) here, under Guides. But there are also other sections where a mention is relevant. Let’s mention it: • under Description, since it is as useful as the other tutorials already mentioned there for those who are interested; • under Terminology, since it complements gitglossary(7) as a pedagogical rather than reference source for the core terms;[1] and • under See Also, since the other tutorials (plus the user manual) are mentioned there. We don’t need to mention it under Further Documentation since we now mention it under Description. † 1: See dee80940 (doc: add an explanation of Git's data model, 2025-11-12): `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. Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano --- Documentation/git.adoc | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/Documentation/git.adoc b/Documentation/git.adoc index 8a5cdd3b3d..6f0075f918 100644 --- a/Documentation/git.adoc +++ b/Documentation/git.adoc @@ -25,7 +25,8 @@ and full access to internals. See linkgit:gittutorial[7] to get started, then see linkgit:giteveryday[7] for a useful minimum set of commands. The link:user-manual.html[Git User's Manual] has a more -in-depth introduction. +in-depth introduction. See linkgit:gitdatamodel[7] if you want to +learn about the data model and important terminology. After you mastered the basic concepts, you can come back to this page to learn what commands Git offers. You can learn more about @@ -469,7 +470,9 @@ Higher level SCMs may provide and manage additional information in the Terminology ----------- -Please see linkgit:gitglossary[7]. +Please see linkgit:gitglossary[7]. See linkgit:gitdatamodel[7] for a +discussion of the core data model, which includes important terminology +used throughout the documentation. Environment Variables @@ -1199,8 +1202,9 @@ SEE ALSO -------- linkgit:gittutorial[7], linkgit:gittutorial-2[7], linkgit:giteveryday[7], linkgit:gitcvs-migration[7], -linkgit:gitglossary[7], linkgit:gitcore-tutorial[7], -linkgit:gitcli[7], link:user-manual.html[The Git User's Manual], +linkgit:gitglossary[7], linkgit:gitdatamodel[7], +linkgit:gitcore-tutorial[7], linkgit:gitcli[7], +link:user-manual.html[The Git User's Manual], linkgit:gitworkflows[7] GIT From b27722d03144ec723ab20dc337ff21be2ea6a0b7 Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Sun, 23 Aug 2026 13:32:48 +0200 Subject: [PATCH 3/4] doc: glossary: link four of the terms to gitdatamodel(7) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four of the terms in the glossary are discussed in gitdatamodel(7). Let’s link to the data model page from the glossary. The phrasing needs to be tweaked based on what gitdatamodel(7) offers for each term compared to the glossary, or even other pages (see the git-reflog(1) mention). For instance, the ref/reference discussion can be called a “see also” since the glossary here already goes into detail. On the other hand, gitdatamodel(7) offers more details on the subject of “the index”. Let’s also add gitdatamodel(7) to See Also. It is at least as relevant as the other tutorial pages that are already mentioned. Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano --- Documentation/gitglossary.adoc | 1 + Documentation/glossary-content.adoc | 13 ++++++++++--- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/Documentation/gitglossary.adoc b/Documentation/gitglossary.adoc index 0e85be4847..b046d9cb29 100644 --- a/Documentation/gitglossary.adoc +++ b/Documentation/gitglossary.adoc @@ -16,6 +16,7 @@ include::glossary-content.adoc[] SEE ALSO -------- +linkgit:gitdatamodel[7], linkgit:gittutorial[7], linkgit:gittutorial-2[7], linkgit:gitcvs-migration[7], diff --git a/Documentation/glossary-content.adoc b/Documentation/glossary-content.adoc index 8c4e9dd3be..52301a56dd 100644 --- a/Documentation/glossary-content.adoc +++ b/Documentation/glossary-content.adoc @@ -251,7 +251,8 @@ for a more flexible and robust system to do the same thing. as objects. The index is a stored version of your <>. Truth be told, it can also contain a second, and even a third version of a working tree, which are used - when <>. + when <>. See "THE INDEX" in + linkgit:gitdatamodel[7] for details. [[def_index_entry]]index entry:: The information regarding a particular file, stored in the @@ -290,7 +291,8 @@ This commit is referred to as a "merge commit", or sometimes just a [[def_object]]object:: The unit of storage in Git. It is uniquely identified by the <> of its contents. Consequently, an - object cannot be changed. + object cannot be changed. See "OBJECTS" in + linkgit:gitdatamodel[7] for details. [[def_object_database]]object database:: Stores a set of "objects", and an individual <> is @@ -587,12 +589,17 @@ extended in the future: Different subhierarchies are used for different purposes. For example, the `refs/heads/` hierarchy is used to represent local branches whereas the `refs/tags/` hierarchy is used to represent local tags.. ++ +See also "REFERENCES" in linkgit:gitdatamodel[7]. [[def_reflog]]reflog:: A reflog shows the local "history" of a ref. In other words, it can tell you what the 3rd last revision in _this_ repository was, and what was the current state in _this_ repository, - yesterday 9:14pm. See linkgit:git-reflog[1] for details. + yesterday 9:14pm. ++ +See "REFLOGS" in linkgit:gitdatamodel[7] for a short explanation of the +format. See linkgit:git-reflog[1] for details. [[def_refspec]]refspec:: A "refspec" is used by <> and From 7b2ce85f4c55b4d8eb9c9decd964eb3d899af5ba Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Sun, 23 Aug 2026 13:32:49 +0200 Subject: [PATCH 4/4] doc: datamodel: link to the glossary We linked from the glossary to the data model page in the last commit. It can also be useful to link the other way for readers who might want to reference more terminology. Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano --- Documentation/gitdatamodel.adoc | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Documentation/gitdatamodel.adoc b/Documentation/gitdatamodel.adoc index dcfdff0346..d588630e63 100644 --- a/Documentation/gitdatamodel.adoc +++ b/Documentation/gitdatamodel.adoc @@ -24,6 +24,8 @@ Git's core operations use 4 kinds of data: 3. <>, also known as the staging area 4. <>: logs of changes to references ("ref log") +See linkgit:gitglossary[7] for a comprehensive terminology reference. + [[objects]] OBJECTS ------- @@ -300,6 +302,10 @@ $ git reflog main --date=iso --no-decorate 4ccb6d7 main@{2025-09-29 15:16:48 -0400}: commit (initial): Initial commit ---- +SEE ALSO +-------- +linkgit:gitglossary[7] + GIT --- Part of the linkgit:git[1] suite