Definition

Shallow commits do have parents, but not in the shallow repo, and therefore grafts are introduced pretending that these commits have no parents.

$GIT_DIR/shallow lists commit object names and tells Git to pretend as if they are root commits (e.g. "git log" traversal stops after showing them; "git fsck" does not complain saying the commits listed on their "parent" lines do not exist).

Each line contains exactly one object name. When read, a commit_graft will be constructed, which has nr_parent < 0 to make it easier to discern from user provided grafts.

Note that the shallow feature could not be changed easily to use replace refs: a commit containing a mergetag is not allowed to be replaced, not even by a root commit. Such a commit can be made shallow, though. Also, having a shallow file explicitly listing all the commits made shallow makes it a lot easier to do shallow-specific things such as to deepen the history.

Since fsck-objects relies on the library to read the objects, it honours shallow commits automatically.

There are some unfinished ends of the whole shallow business:

To make a shallow clone, you can call "git-clone --depth 20 repo". The result contains only commit chains with a length of at most 20. It also writes an appropriate $GIT_DIR/shallow.

You can deepen a shallow repository with "git-fetch --depth 20 repo branch", which will fetch branch from repo, but stop at depth 20, updating $GIT_DIR/shallow.

The special depth 2147483647 (or 0x7fffffff, the largest positive number a signed 32-bit integer can contain) means infinite depth.