Re: [PATCH v2] doc: add a explanation of Git's data model

From: Patrick Steinhardt <ps@pks.im>
Date: Oct 10, 2025, 11:51 UTC
Message-ID: <aOjzQ7-88m5e_YJl@pks.im>
In-Reply-To: <pull.1981.v2.git.1759931621272.gitgitgadget@gmail.com>

On Wed, Oct 08, 2025 at 01:53:41PM +0000, Julia Evans via GitGitGadget wrote: [snip]

Show 9 quoted lines

> +[[blob]]
> +blobs::
> +    A blob is how Git represents a file. A blob object contains the
> +    file's contents.
> ++
> +
> +NOTE: Storing a new blob for every new version of a file can use a
> +lot of disk space. To handle this, Git periodically runs repository
> +maintenance with linkgit:git-gc[1]. Part of this maintenance is

By the way, this isn't true nowadays: Git does not use `git gc --auto` anymore, but instead `git maintenance run --auto`. So we really should be linking to "linkgit:git-maintenance[1]".

This tool _by default_ executes git-gc(1). But it can be configured to use alternative strategies, and when using scalar(1) we actually use a different strategy.

[snip]

Show 17 quoted lines

> +[[references]]
> +REFERENCES
> +----------
> +
> +References are a way to give a name to a commit.
> +It's easier to remember "the changes I'm working on are on the `turtle`
> +branch" than "the changes are in commit bb69721404348e".
> +Git often uses "ref" as shorthand for "reference".
> +
> +References can either be:
> +
> +1. References to an object ID, usually a <<commit,commit>> ID
> +2. References to another reference. This is called a "symbolic reference".
> +
> +References are stored in a hierarchy, and Git handles references
> +differently based on where they are in the hierarchy.
> +Most references are under `refs/`. Here are the main types:

Not quite true. Pseudo refs are outside the hierarchy and are in fact treated differently. But root refs are treated the same as any other reference.

    References are stored in a hierarchy. While most references are
    stored in the "refs/" hierarchy, some references with special
    meaning like for example "HEAD" are stored directly in the root of
    the hierarchy.

I don't really think we should get into root refs vs pseudo refs here, so maybe this is sufficient?

[snip]

Show 10 quoted lines

> +[[other-refs]]
> +Other references::
> +    Git tools may create references anywhere under `refs/`.
> +    For example, linkgit:git-stash[1], linkgit:git-bisect[1],
> +    and linkgit:git-notes[1] all create their own references
> +    in `refs/stash`, `refs/bisect`, etc.
> +    Third-party Git tools may also create their own references.
> ++
> +Git may also create references other than `HEAD` at the base of the
> +hierarchy, like `ORIG_HEAD`.

Maybe append: "These references are called root refs (see linkgit:gitglossary[7])."

Patrick