git-series internals
====================
Requirements
------------
The format git-series uses to store each patch series ensures that standard git
tools can always handle a git-series repository. In particular:
- All commits and objects in the history and metadata of every series must
remain reachable via git's normal object reachability algorithms, so that git
will never discard the history or metadata of a series.
- Transferring a git-series repository via git's standard protocols must
transfer all series including history and metadata, without any extensions to
the git protocols.
Refs
----
git-series stores the series ref for a patch series named `NAME` in
`refs/heads/git-series/NAME`. This will appear to git as a branch named
`git-series/NAME`. From that ref, git can reach all the information git-series
tracks about a patch series, so sending or receiving that ref brings along all
the information git-series needs.
git-series maintains a symbolic ref `refs/SHEAD` pointing to the current
series. If a repository does not have a current series, SHEAD will not exist.
git-series commits
------------------
git-series stores each version of a patch series as one commit object. The
`git-series/NAME` ref refers to commit corresponding to the current version of
the patch series NAME. The tree object within each git-series commit acts like
a key-value store, with tree entry names as keys; the tree entry `series`
references the last commit of the patch series itself.
In this documentation, a "git-series commit" refers to a commit corresponding
to a version of an entire patch series, as distinguished from a commit
corresponding to one patch within a patch series.
A git-series commit can have two types of parent commits: those connecting the
history of the patch series, and those referencing gitlink commits that also
appear in the git-series commit's tree. A git-series commit can have any
number of either type of parent, but all of the parents connecting the history
of the patch series will always appear before any of the parents referencing
gitlink commits.
The parents connecting the history of the patch series, if any, point to
previous git-series commits representing previous versions of the patch series;
a git-series commit with more than one such parent represents a git-series
merge commit. The remaining parents of each git-series commit correspond to
commits referenced as gitlinks (tree entries with mode 160000) within the
commit's tree; this ensures that git can reach all of those commits. (Note
that git's traversal algorithm does not follow gitlink commits within tree
objects, so without these additional parent links, git would consider these
gitlink commits unreachable and discard them.)
The parents of each git-series commit that reference gitlinks in that
git-series commit's tree do not appear in any particular order; do not assume
that the `series` object or any other gitlink appears at any particular
position within the parents list. These parents exist only to make commits
reachable and transferable by git. Always look up commits via named tree
entries within the git-series commit's tree object.
In the root git-series commit, all the parent commits correspond to gitlinks
within the git-series commit's tree. This will not occur for any non-root
commit of a git-series. Algorithms trying to walk git-series commits should
filter out parents that appear in the git-series commit's tree. (This does not
require a recursive tree walk; the gitlinks within the git-series commit's tree
will appear in the top-level tree object.)
git-series tree entries
-----------------------
The tree within a git-series commit can contain the following entries:
- `series`: Every git-series tree must contain this entry, as a gitlink with
mode 160000. This identifies the last commit in the patch series.
- `base`: If this exists, it must refer to a gitlink with mode 160000. This
identifies the base commit for the patch series. The patch series consists
of the commits reachable from `series` and not reachable from `base`:
`base`..`series`. Many git-series commands require `base`, but a patch
series does not have to have a `base`.
- `cover`: If this exists, it must refer to a blob with mode 100644. This
provides a cover letter for the patch series. This blob should contain UTF-8
text.
git-series staged changes and "working directory"
-------------------------------------------------
Like git, git-series allows staging part of all of the changes to the patch
series for a commit, or committing all the changes directly via `git series
commit -a`. However, git-series does not maintain a "working directory"
directly. Instead, git-series tracks the staged and unstaged changes to a
patch series named NAME via commits referenced by
`refs/git-series-internals/staged/NAME` and
`refs/git-series-internals/working/NAME`. The tree of each of those commits
may contain any of the standard git-series tree entries. (If the series has
nothing staged, the "staged" ref will not exist.) These commits will also have
all of the corresponding gitlink entries as parents, to keep them reachable by
git.
The `working` commit for a patch series tracks the current state of the patch
series. For example, setting a base with `git series base` or a cover letter
with `git series cover` will store the new base or cover letter as `base` or
`cover` in the tree of the commit referenced from the working ref. git-series
commands will keep the `series` entry of the working tree referring to the
current HEAD.
The `staged` commit for a patch series, if present, tracks the staged changes
to the patch series. `git series add` adds changes from `working` to `staged`,
and `git series unadd` removes changes from `staged`.
If a series does not have a series ref `refs/heads/git-series/NAME`, but has a
staged or working ref, the series still exists, with no series commits. This
can happen by running `git series start NAME`, making some changes without
committing, and then running `git series detach`. git-series treats that as an
existing series, and allows checking it out. This preserves work in progress
on an un-started series.