On Thu, Nov 15 2018, sxe...@google.com wrote:
> +Detailed design
> +===============
> +Obsolescence information is stored as a graph of meta-commits. A meta-commit
> is
> +a specially-formatted merge commit that describes how one commit was created
> +from others.
> +
> +Meta-commits look like this:
> +
> +$ git cat-file -p <example_meta_commit>
> +tree 4b825dc642cb6eb9a060e54bf8d69288fbee4904
> +parent aa7ce55545bf2c14bef48db91af1a74e2347539a
> +parent d64309ee51d0af12723b6cb027fc9f195b15a5e9
> +parent 7e1bbcd3a0fa854a7a9eac9bf1eea6465de98136
> +author Stefan Xenos <sxe...@gmail.com> 1540841596 -0700
> +committer Stefan Xenos <sxe...@gmail.com> 1540841596 -0700
> +parent-type content
> +parent-type obsolete
> +parent-type origin
> +
> +This says “commit aa7ce555 makes commit d64309ee obsolete. It was created by
> +cherry-picking commit 7e1bbcd3”.
> +
> +The tree for meta-commits is always the empty tree whose hash matches
> +4b825dc642cb6eb9a060e54bf8d69288fbee4904 exactly, but future versions of git
> may
> +attach other trees here. For forward-compatibility fsck should ignore such
> trees
> +if found on future repository versions. Similarly, current versions of git
> +should always fill in an empty commit comment and tools like fsck should
> ignore
> +the content of the commit comment if present in a future repository version.
> +This will allow future versions of git to add metadata to the meta-commit
> +comments or tree without breaking forwards compatibility.
> +
> +Parent-type
> +-----------
> +The “parent-type” field in the commit header identifies a commit as a
> +meta-commit and indicates the meaning for each of its parents. It is never
> +present for normal commits. It is a list of enum values whose order matches
> the
> +order of the parents. Possible parent types are:
> +
> +- content: the content parent identifies the commit that this meta-commit is
> + describing.
> +- obsolete: indicates that this parent is made obsolete by the content
> parent.
> +- origin: indicates that this parent was generated from the given commit.
> +
> +There must be exactly one content parent for each meta-commit and it is
> always
> +be the first parent. The content commit will always be a normal commit and
> not a
> +meta-commit. However, future versions of git may create meta-commits for
> other
> +meta-commits and the fsck tool must be aware of this for forwards
> compatibility.
> +
> +A meta-commit can have zero or more obsolete parents. An amend operation
> creates
> +a single obsolete parent. A merge used to resolve divergence (see divergence,
> +below) will create multiple obsolete parents. A meta-commit may have zero
> +obsolete parents if it describes a cherry-pick or squash merge that copies
> one
> +or more commits but does not replace them.
> +
> +A meta-commit can have zero or more origin parents. A cherry-pick creates a
> +single origin parent. Certain types of squash merge will create multiple
> origin
> +parents.
> +
> +An obsolete parent or origin parent may be either a normal commit (indicating
> +the oldest-known version of a change) or another meta-commit (for a change
> that
> +has already been modified one or more times).
I think it's worth pointing out for those that are rusty on commit
object details (but I checked) is that the reason for it not being:
tree 4b825dc642cb6eb9a060e54bf8d69288fbee4904
parent aa7ce55545bf2c14bef48db91af1a74e2347539a
parent-type content
parent d64309ee51d0af12723b6cb027fc9f195b15a5e9
parent-type obsolete
parent 7e1bbcd3a0fa854a7a9eac9bf1eea6465de98136
parent-type origin
author Stefan Xenos <sxe...@gmail.com> 1540841596 -0700
committer Stefan Xenos <sxe...@gmail.com> 1540841596 -0700
Which would be easier to read, is that we're very sensitive to the order
of the first few fields (tree -> parent -> author -> committer) and fsck
will error out if we interjected a new field.
