[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

[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

[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

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

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 v2 0/4] doc: advertize gitdatamodel(1)

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Topic name (applied): kh/doc-datamodel

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 data model page.

§ Testing

Testing done on v1. No tests done for v2.

§ Changes in v2

Thanks to Patrick for reviewing the first round.

Correct commit messages for:

• Patch 1/4, “list gitdatamodel(7) as a concept guide”
• Patch 2/4, “link to the gitdatamodel(7) tutorial”

§ Link to v1

https://lore.kernel.org/git/CV_doc_datamodel_advertize.bea@msgid.xyz/

§ Aside about context lines in gitlossary(7)

Nothing to do with this topic, but I noticed this “..” in gitglossary(7):

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

From 74b50a58 (Documentation/glossary: define root refs as refs,
2024-05-15) by Patrick. Is that intentional, like an ellipsis? In other
words listing heads, then tags, then using ellipsis to communicate “you
see the pattern here”.

[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(-)

Interdiff against v1:
Range-diff against v1:
1:  7fbff6b7d1f ! 1:  35832098717 doc: git: list gitdatamodel(7) as a concept guide
    @@ Commit message
     
         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.
    +    anywhere.
     
         Let’s start by listing it under Guides in git(1) and with `git help
         --guides`.
2:  916e9f7d46f ! 2:  3d8c4334785 doc: git: link to the gitdatamodel(7) tutorial
    @@ Metadata
      ## Commit message ##
         doc: git: link to the gitdatamodel(7) tutorial
     
    -    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.
    +    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 as useful as the other tutorials already
    -      mentioned there for those who are interested;
    +    • 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
3:  5c83788e417 = 3:  04802040a8d doc: glossary: link four of the terms to gitdatamodel(7)
4:  f8fb18b5f98 = 4:  5e8911beb4e doc: datamodel: link to the glossary

base-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc
-- 
2.55.0.13.g85d2d65e389

[PATCH v2 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
anywhere.

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

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • Msg: s/everywhere/anywhere/[1]
      🔗 1: https://lore.kernel.org/git/aohDEKEs82MaWECV@pks.im/#t

 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

[PATCH v2 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(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 <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • Msg: Correct section: s/gitdatamodel(1)/gitdatamodel(7)/[1]
    • Msg: Missing “is”[1]
    • Msg: Correct “on another page” which refers to git(1)—the same
      page that we are changing.[2] This is a mistake from my own
      iterations since this started as the first commit and I had to
      reword from: not mentioned yet; mentioned with `git help
      --guides`; (realizes that it is also automatically included in
      Guides now) ...
    • Msg: s/other places/other sections/[2]
      🔗 1: https://lore.kernel.org/git/aohDFdjPU0t2d9_8@pks.im/
      † 2: Self review
    ---
    v1:
    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

[PATCH v2 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>
---

Notes (series):
    V2:
    No changes.
    
    I reread the Ref entry in the glossary and compared it to the
    Reference entry on the data model page. These two texts cover
    similar things (except the “irregular refs”, only covered in the
    glossary). The data model page is slightly more conceptual in tone.
    
    That’s why I originally went with just “see also” instead of for
    example “see also ... more details” or “see also ... for a more
    conceptual overview). They are too similar to distinguish further
    in this context.

 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 v2 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):
    v1:
    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

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

[Patrick Steinhardt]

On Sun, Aug 23, 2026 at 01:32:45PM +0200, kristofferhaugsbakk@fastmail.com wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> 
> Topic name (applied): kh/doc-datamodel
> 
> 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 data model page.
> 
> § Testing
> 
> Testing done on v1. No tests done for v2.
> 
> § Changes in v2
> 
> Thanks to Patrick for reviewing the first round.
> 
> Correct commit messages for:
> 
> • Patch 1/4, “list gitdatamodel(7) as a concept guide”
> • Patch 2/4, “link to the gitdatamodel(7) tutorial”

Thanks, I'm happy with this version.

Patrick

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

[Kristoffer Haugsbakk]

On Mon, Aug 31, 2026, at 09:19, Patrick Steinhardt wrote:
> On Sun, Aug 23, 2026 at 01:32:45PM +0200,
> kristofferhaugsbakk@fastmail.com wrote:
>>[snip]
>
> Thanks, I'm happy with this version.

Thanks for your reviews.

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

[Julia Evans]

On Sun, Aug 23, 2026, at 7:32 AM, kristofferhaugsbakk@fastmail.com wrote:
> 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):
>     v1:
>     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.

I'd prefer to put this in SEE ALSO instead. 
Also "comprehensive terminology reference" might be a bit aspirational
like you say. Maybe just "terminology reference"?

Thanks for adding these links! 

- Julia

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

[Kristoffer Haugsbakk]

On Wed, Sep 2, 2026, at 15:32, Julia Evans wrote:
> On Sun, Aug 23, 2026, at 7:32 AM, kristofferhaugsbakk@fastmail.com wrote:
>>[snip]
>> 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.
>
> I'd prefer to put this in SEE ALSO instead.

It’s also in See Also. Do you mean put the whole sentence in See Also
instead of just this link? I have never seen See Also be used for more
than just a comma-separated list of links.

I’m also okay with just dropping it.

> Also "comprehensive terminology reference" might be a bit aspirational
> like you say. Maybe just "terminology reference"?

Yeah. The idea behind having any adjective or modifier was that just
“terminology reference” seemed to not contrast the roles of these two
pages enough. Since they are both about terminology after all, just one
of them drills down into the core concepts/terminology.

Or it could be

   ... terminology reference for all of Git.

Which seems a bit much and wordy. Or maybe

   ... general terminology reference.

>
> Thanks for adding these links!

Thanks for reviewing. :·)

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

[Julia Evans]

On Wed, Sep 2, 2026, at 1:04 PM, Kristoffer Haugsbakk wrote:
> On Wed, Sep 2, 2026, at 15:32, Julia Evans wrote:
>> On Sun, Aug 23, 2026, at 7:32 AM, kristofferhaugsbakk@fastmail.com wrote:
>>>[snip]
>>> 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.
>>
>> I'd prefer to put this in SEE ALSO instead.
>
> It’s also in See Also. Do you mean put the whole sentence in See Also
> instead of just this link? I have never seen See Also be used for more
> than just a comma-separated list of links.
>
> I’m also okay with just dropping it.

Ah, I didn't see it in See Also, I'm still struggling to get used to this email-based
patch review workflow :)

I think just dropping it is fine.

>> Also "comprehensive terminology reference" might be a bit aspirational
>> like you say. Maybe just "terminology reference"?
>
> Yeah. The idea behind having any adjective or modifier was that just
> “terminology reference” seemed to not contrast the roles of these two
> pages enough. Since they are both about terminology after all, just one
> of them drills down into the core concepts/terminology.
>
> Or it could be
>
>    ... terminology reference for all of Git.
>
> Which seems a bit much and wordy. Or maybe
>
>    ... general terminology reference.
>
>>
>> Thanks for adding these links!
>
> Thanks for reviewing. :·)

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

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Topic name (applied): kh/doc-datamodel

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 data model page.

§ Testing

Testing done on v1. No tests done for v2 or v3.

§ Changes in v3

Thanks to Patrick and Julia for reviewing.

Following up on Julia’s review. See the interdiff/range diff and
patch notes. The patch notes also documents the changes from the
previous rounds by the way.

§ Link to v2

https://lore.kernel.org/git/V2_CV_doc_datamodel_advertize.c20@msgid.xyz/#t

§ Aside about context lines in gitlossary(7)

(see v1 & v2; no one commented on this)

[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     |  4 ++++
 Documentation/gitglossary.adoc      |  1 +
 Documentation/glossary-content.adoc | 13 ++++++++++---
 command-list.txt                    |  1 +
 5 files changed, 24 insertions(+), 7 deletions(-)

Interdiff against v2:
diff --git a/Documentation/gitdatamodel.adoc b/Documentation/gitdatamodel.adoc
index d588630e633..56b7635c199 100644
--- a/Documentation/gitdatamodel.adoc
+++ b/Documentation/gitdatamodel.adoc
@@ -24,8 +24,6 @@ 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
 -------
Range-diff against v2:
1:  35832098717 = 1:  35832098717 doc: git: list gitdatamodel(7) as a concept guide
2:  3d8c4334785 = 2:  3d8c4334785 doc: git: link to the gitdatamodel(7) tutorial
3:  04802040a8d = 3:  04802040a8d doc: glossary: link four of the terms to gitdatamodel(7)
4:  5e8911beb4e ! 4:  ef9469244f2 doc: datamodel: link to the glossary
    @@ Commit message
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Documentation/gitdatamodel.adoc ##
    -@@ Documentation/gitdatamodel.adoc: 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
    - -------
     @@ Documentation/gitdatamodel.adoc: $ git reflog main --date=iso --no-decorate
      4ccb6d7 main@{2025-09-29 15:16:48 -0400}: commit (initial): Initial commit
      ----

base-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc
-- 
2.55.0.13.g335083658c8

[PATCH v3 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
anywhere.

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

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • Msg: s/everywhere/anywhere/[1]
      🔗 1: https://lore.kernel.org/git/aohDEKEs82MaWECV@pks.im/#t

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

[PATCH v3 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(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 <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • Msg: Correct section: s/gitdatamodel(1)/gitdatamodel(7)/[1]
    • Msg: Missing “is”[1]
    • Msg: Correct “on another page” which refers to git(1)—the same
      page that we are changing.[2] This is a mistake from my own
      iterations since this started as the first commit and I had to
      reword from: not mentioned yet; mentioned with `git help
      --guides`; (realizes that it is also automatically included in
      Guides now) ...
    • Msg: s/other places/other sections/[2]
      🔗 1: https://lore.kernel.org/git/aohDFdjPU0t2d9_8@pks.im/
      † 2: Self review
    ---
    v1:
    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.g335083658c8

[PATCH v3 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>
---

Notes (series):
    v2:
    No changes.
    
    I reread the Ref entry in the glossary and compared it to the
    Reference entry on the data model page. These two texts cover
    similar things (except the “irregular refs”, only covered in the
    glossary). The data model page is slightly more conceptual in tone.
    
    That’s why I originally went with just “see also” instead of for
    example “see also ... more details” or “see also ... for a more
    conceptual overview). They are too similar to distinguish further
    in this context.

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

[PATCH v3 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):
    v3:
    • Drop the running text mention of gitglossary(7). Just use the link in See
      Also.[1]
      🔗 1: https://lore.kernel.org/git/5e12e3ad-a80c-4c7b-81f7-e028e461fdd1@app.fastmail.com/#t

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

diff --git a/Documentation/gitdatamodel.adoc b/Documentation/gitdatamodel.adoc
index dcfdff0346f..56b7635c199 100644
--- a/Documentation/gitdatamodel.adoc
+++ b/Documentation/gitdatamodel.adoc
@@ -300,6 +300,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.g335083658c8