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

From: Patrick Steinhardt <ps@pks.im>
Date: Oct 15, 2025, 06:24 UTC
Message-ID: <aO8-NtJPNBAM2tVn@pks.im>
In-Reply-To: <pull.1981.v3.git.1760476346040.gitgitgadget@gmail.com>

On Tue, Oct 14, 2025 at 09:12:26PM +0000, Julia Evans via GitGitGadget wrote: [snip]

Show 29 quoted lines

> +[[commit]]
> +commits::
> +    A commit contains these required fields
> +    (though there are other optional fields):
> ++
> +1. All the *files* in the commit, stored as the *<<tree,tree>>* ID of
> +   the commit's base directory.
> +2. Its *parent commit ID(s)*. The first commit in a repository has 0 parents,
> +  regular commits have 1 parent, merge commits have 2 or more parents
> +3. An *author* and the time the commit was authored
> +4. A *committer* and the time the commit was committed.
> +   If you cherry-pick (linkgit:git-cherry-pick[1]) someone else's commit,
> +   then they will be the author and you'll be the committer.
> +5. A *commit message*
> ++
> +Here's how an example commit is stored:
> ++
> +----
> +tree 1b61de420a21a2f1aaef93e38ecd0e45e8bc9f0a
> +parent 4ccb6d7b8869a86aae2e84c56523f8705b50c647
> +author Maya <maya@example.com> 1759173425 -0400
> +committer Maya <maya@example.com> 1759173425 -0400
> +
> +Add README
> +----
> ++
> +Like all other objects, commits can never be changed after they're created.
> +For example, "amending" a commit with `git commit --amend` creates a new
> +commit with the same parent.

Let's say "parents" instead of "parent" here so that it also works for root and merge commits.

[snip]

Show 15 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`.
> ++
> +NOTE: By default, Git references are stored as files in the `.git` directory.
> +For example, the branch `main` is stored in `.git/refs/heads/main`.
> +This means that you can't have branches named both `maya` and `maya/some-task`,
> +because there can't be a file and a directory with the same name.

Hm. I think mentioning this can help, but it may also creates questions when someone has a "main" branch but is unable find it in ".git/refs/heads/main" because it has either been packed, or because the repository uses reftables.

I don't really know what to do about this. I think the most sensible thing would be to introduce two man pages gitformat-reffiles(5) and gitformat-reftables(5) that we can reference here for further reading.

[snip]

Show 5 quoted lines

> +[[reflogs]]
> +REFLOGS
> +-------
> +
> +Git stores a history called a "reflog" for every branch, remote-tracking

I think it's a bit unclear what "history" means here. Maybe:

    Git stores a "reflog" for every branch, remote-tracking branch and
    "HEAD" that contains the annotated history of all updates for a
    particular reference. This means...

Other than those handful of comments I'm happy with the current version, thanks!

Patrick