Skip to content

Latest commit

 

History

History
120 lines (99 loc) · 6.09 KB

INTERNALS.md

File metadata and controls

120 lines (99 loc) · 6.09 KB
Raw

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.