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

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

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

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

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

On Thu, Aug 20, 2026 at 08:55:21PM +0200, kristofferhaugsbakk@fastmail.com wrote:

Nit: s/everywhere/anywhere?

Makes sense.

Patrick

On Thu, Aug 20, 2026 at 08:55:22PM +0200, kristofferhaugsbakk@fastmail.com wrote:

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

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

Patrick

On Fri, Aug 21, 2026, at 14:22, Patrick Steinhardt wrote:

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

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

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

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

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

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

On Sun, Aug 23, 2026 at 01:32:45PM +0200, kristofferhaugsbakk@fastmail.com wrote:

Thanks, I'm happy with this version.

Patrick

On Mon, Aug 31, 2026, at 09:19, Patrick Steinhardt wrote:

Thanks for your reviews.

On Sun, Aug 23, 2026, at 7:32 AM, kristofferhaugsbakk@fastmail.com wrote:

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

On Wed, Sep 2, 2026, at 15:32, Julia Evans wrote:

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.

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 reviewing. :·)

On Wed, Sep 2, 2026, at 1:04 PM, Kristoffer Haugsbakk wrote:

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.

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:

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

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

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

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