Re: [PATCH v5] doc: add an explanation of Git's data model

[Junio C Hamano <gitster@pobox.com>]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> diff --git a/Documentation/gitdatamodel.adoc b/Documentation/gitdatamodel.adoc
> new file mode 100644
> index 0000000000..1cefbb4833
> --- /dev/null
> +++ b/Documentation/gitdatamodel.adoc
> @@ -0,0 +1,296 @@
> +gitdatamodel(7)
> +===============
> +
> +NAME
> +----
> +gitdatamodel - Git's core data model
> +
> +SYNOPSIS
> +--------
> +gitdatamodel
> +
> +DESCRIPTION
> +-----------
> +
> +It's not necessary to understand Git's data model to use Git, but it's
> +very helpful when reading Git's documentation so that you know what it
> +means when the documentation says "object", "reference" or "index".
> +
> +Git's core operations use 4 kinds of data:
> +
> +1. <<objects,Objects>>: commits, trees, blobs, and tag objects
> +2. <<references,References>>: branches, tags,
> +   remote-tracking branches, etc
> +3. <<index,The index>>, also known as the staging area
> +4. <<reflogs,Reflogs>>: logs of changes to references ("ref log")
> +
> +[[objects]]
> +OBJECTS
> +-------
> +
> +All of the commits and files in a Git repository are stored as "Git objects".
> +Git objects never change after they're created, and every object has an ID,
> +like `1b61de420a21a2f1aaef93e38ecd0e45e8bc9f0a`.
> +
> +This means that if you have an object's ID, you can always recover its
> +exact contents as long as the object hasn't been deleted.
> +
> +Every object has:
> +
> +[[object-id]]
> +1. an *ID* (aka "object name"), which is a cryptographic hash of its
> +  type and contents.
> +  It's fast to look up a Git object using its ID.
> +  This is usually represented in hexadecimal, like
> +  `1b61de420a21a2f1aaef93e38ecd0e45e8bc9f0a`.
> +2. a *type*. There are 4 types of objects:
> +   <<commit,commits>>, <<tree,trees>>, <<blob,blobs>>,
> +   and <<tag-object,tag objects>>.
> +3. *contents*. The structure of the contents depends on the type.
> +
> +Here's how each type of object is structured:
> +
> +[[commit]]
> +commit::
> +    A commit contains these required fields
> +    (though there are other optional fields):
> ++
> +1. The full directory structure of all the files in that version of the
> +   repository and each file's contents, stored as the *<<tree,tree>>* ID
> +   of the commit's base directory.

"base directory" is a new term; I think we most often use
"top-level" directory (in various spellings).

$ git grep -e 'base directory' -e 'level directory' Documentation/

> +[[tree]]
> +tree::
> +    A tree is how Git represents a directory.
> +    It can contain files or other trees (which are subdirectories).
> +    It lists, for each item in the tree:
> ++
> +1. The *filename*, for example `hello.py`
> +2. The *file mode*. Git has these file modes. which are only

"has these" -> "uses only these" to clarify that this is an
exhaustive enumeration and users cannot invent 100664 and others,
which is a mistake Git itself used to make/allow.

> +[[tag-object]]
> +tag object::
> +    Tag objects contain these required fields
> +    (though there are other optional fields):
> ++
> +1. The object *ID* it references
> +2. The object *type*

I would rephrase these to

    1. The *ID* of the object it references
    2. The *type* of the object it references

because (1) a tag object references another object, not ID.  To name
the object it reference, it uses the object name of it, but just
like your name is not you, object name is not the object (it merely
is *one* way to refer to it). (2) unless it is very clear to readers
that "The object" in 1. and 2. refer to the same object, 2. invites
a question "type of which object?".

> +[[branch]]
> +branches: `refs/heads/<name>`::
> +    A branch refers to a commit ID.

A branch refers to a commit object (by its ID).  Ditto for tags.

> +NOTE: Git may delete objects that aren't "reachable" from any reference.
> +An object is "reachable" if we can find it by following tags to whatever
> +they tag, commits to their parents or trees, and trees to the trees or
> +blobs that they contain.
> +For example, if you amend a commit, with `git commit --amend`,
> +the old commit will usually not be reachable, so it may be deleted eventually.
> +Reachable objects will never be deleted.

Very good write-up.  As we would touch upon reflog later in the same
document, we may want to extend the "amend" example a bit, perhaps
like

    Note: Git never deletes objects that are "reachable".  An object
    is "reachable" if ....  An unreachable object may be deleted.

    For example, ... a newly created commit will replace the old
    commit and the current branch ref points at the new commit.  The
    old commit is recorded in the <<reflogs,reflog>> of the current
    branch, so it is still "reachable", but sufficiently old reflog
    entries are expired away, the old commit may become unreachable
    at that point, and would get deleted.

Other than the above, I found everything very nicely written.

Thanks.