[PATCH 0/4] doc: advertize gitdatamodel(1)

[PATCH 0/4] doc: advertize gitdatamodel(1)

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Topic name: kh/doc-datamodel-advertize

Topic summary: gitdatamodel(7) is not linked to from anywhere. Let’s
mention it on other documentation pages and add a link to the glossary on
the datamodel page.

§ Testing

Other than the usual documentation testing, I was unsure if this would trip
any tests in the t/ directory which tests what output you get from `git
help --guides` or whatever else. So I merged today’s `seen` in in addition
to this topic and ran `cd t && make test`.

[1/4] doc: git: list gitdatamodel(7) as a concept guide
[2/4] doc: git: link to the gitdatamodel(7) tutorial
[3/4] doc: glossary: link four of the terms to gitdatamodel(7)
[4/4] doc: datamodel: link to the glossary

 Documentation/git.adoc              | 12 ++++++++----
 Documentation/gitdatamodel.adoc     |  6 ++++++
 Documentation/gitglossary.adoc      |  1 +
 Documentation/glossary-content.adoc | 13 ++++++++++---
 command-list.txt                    |  1 +
 5 files changed, 26 insertions(+), 7 deletions(-)


base-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc
-- 
2.55.0.13.g85d2d65e389

[PATCH 1/4] doc: git: list gitdatamodel(7) as a concept guide

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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
everywhere.

Let’s start by listing it under Guides in git(1) and with `git help
--guides`.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 command-list.txt | 1 +
 1 file changed, 1 insertion(+)

diff --git a/command-list.txt b/command-list.txt
index 21b802c4202..63ae2a67c94 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
-- 
2.55.0.13.g85d2d65e389

Re: [PATCH 1/4] doc: git: list gitdatamodel(7) as a concept guide

[Patrick Steinhardt]

On Thu, Aug 20, 2026 at 08:55:21PM +0200, kristofferhaugsbakk@fastmail.com wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> 
> 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
> everywhere.

Nit: s/everywhere/anywhere?

> diff --git a/command-list.txt b/command-list.txt
> index 21b802c4202..63ae2a67c94 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

Makes sense.

Patrick

[PATCH 2/4] doc: git: link to the gitdatamodel(7) tutorial

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

The previous commit added the first mention of gitdatamodel(1) on
another page, namely in git(1). But there are also other places where
a mention is relevant.

Let’s mention it:

• under Description, since it 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 <code@khaugsbakk.name>
---

Notes (series):
    I have used double spacing for sentences since that seemed to what was
    already in use.

 Documentation/git.adoc | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/Documentation/git.adoc b/Documentation/git.adoc
index 8a5cdd3b3d2..6f0075f9188 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
-- 
2.55.0.13.g85d2d65e389

Re: [PATCH 2/4] doc: git: link to the gitdatamodel(7) tutorial

[Patrick Steinhardt]

On Thu, Aug 20, 2026 at 08:55:22PM +0200, kristofferhaugsbakk@fastmail.com wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> 
> The previous commit added the first mention of gitdatamodel(1) on

It's gitdatamodel(7), not (1).

> another page, namely in git(1). But there are also other places where
> a mention is relevant.
> 
> Let’s mention it:
> 
> • under Description, since it as useful as the other tutorials already

Missing an "is"? -> "since it is as useful as the other"

Patrick

Re: [PATCH 2/4] doc: git: link to the gitdatamodel(7) tutorial

[Kristoffer Haugsbakk]

On Fri, Aug 21, 2026, at 14:22, Patrick Steinhardt wrote:
> On Thu, Aug 20, 2026 at 08:55:22PM +0200,
> kristofferhaugsbakk@fastmail.com wrote:
>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>>
>> The previous commit added the first mention of gitdatamodel(1) on
>
> It's gitdatamodel(7), not (1).
>
>> another page, namely in git(1). But there are also other places where
>> a mention is relevant.
>>
>> Let’s mention it:
>>
>> • under Description, since it as useful as the other tutorials already
>
> Missing an "is"? -> "since it is as useful as the other"

Yes, all your input on this series is correct. I’ll make the
adjustments. Thanks for the careful read.

[PATCH 3/4] doc: glossary: link four of the terms to gitdatamodel(7)

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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 <code@khaugsbakk.name>
---
 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 0e85be48470..b046d9cb293 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 8c4e9dd3bee..52301a56dda 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
 	<<def_working_tree,working tree>>. Truth be told, it can also contain a second, and even
 	a third version of a working tree, which are used
-	when <<def_merge,merging>>.
+	when <<def_merge,merging>>. 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
 	<<def_SHA1,SHA-1>> 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 <<def_object,object>> 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 <<def_fetch,fetch>> and
-- 
2.55.0.13.g85d2d65e389

[PATCH 4/4] doc: datamodel: link to the glossary

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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 <code@khaugsbakk.name>
---

Notes (series):
    But: maybe the See Also link is enough here?
    
    > a comprehensive terminology reference
    
    This is descriptive or aspirational. Either works.

 Documentation/gitdatamodel.adoc | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/gitdatamodel.adoc b/Documentation/gitdatamodel.adoc
index dcfdff0346f..d588630e633 100644
--- a/Documentation/gitdatamodel.adoc
+++ b/Documentation/gitdatamodel.adoc
@@ -24,6 +24,8 @@ Git's core operations use 4 kinds of data:
 3. <<index,The index>>, also known as the staging area
 4. <<reflogs,Reflogs>>: 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
-- 
2.55.0.13.g85d2d65e389