Concepts - arxanas/git-branchless Wiki

Stock Git

In this documentation, "stock Git" refers to Git unaugmented by git-branchless or other tools, in the following sense (Merriam-Webster):

1a: commonly used or brought forward : STANDARD the stock answer

This documentation sometimes contrasts "stock Git" with git-branchless to compare similar operations or specify capabilities which are not part of stock Git.

Working copy

The "working copy" refers to the set of checked out files on disk for the repository. It includes the files of the currently-checked-out commit, as well as any uncommitted changes.

In stock Git, this concept is called the "working copy" or "working tree".

Most stock Git operations operate on the working copy. For performance and ergonomic reasons, git-branchless offers implementations of operations that don't require changes to the working copy. For example, git move is used to carry out a rebase operation entirely in-memory.

Main branch

The "main branch" is the single branch into which all commits are eventually merged/rebased. This is typically named something like master, main, mainline, trunk, etc. The alternative is to have multiple long-lived branches, which might be periodically merged together.

The branchless workflow assumes that all of your work is based off of a single main branch. It's not able to render multiple long-lived branches well.

To configure the name of main branch, see Configuration. When you run git-branchless init, git-branchless will try to guess the name of the main branch in your repository.

Commit graph

The "commit graph" is the directed acyclic graph structure containing all of the commits in the repository. Branches points to commit in the commit graph. Typical development happens by adding a new commit to the commit graph and then moving a branch to point to the new commit.

In stock Git, the term "commit history" is sometimes used to the commit graph or parts of it. We avoid using this terminology in git-branchless because it introduces multiple orthogonal timelines, and it may be ambiguous which timeline's "history" we're referring to. See Bitemporality.

Stock Git also has a feature enabled with core.commitGraph, which is used to optimize commit walks. This feature is unrelated to "commit graphs" as used in in documentation.

Commit stacks

Under a normal Git workflow, a series of commits is usually referred to as a "branch". In git-branchless, there may not be a branch associated with a series of commits. Instead, such a series is called a "commit stack".

In some stock Git workflows, this is called a "patch stack" or "patch series".

Actually, during development with git-branchless, a single commit may diverge into multiple speculative lines of development. This is a broader structure than a single series of commits. In proper computer science terms, a "commit stack" is a subtree of the Git commit graph. But for practical reasons, we don't use terminology like "tree", "branch", or "fork" to describe this structure, because these terms already have different established meanings in Git.

You can consider a commit stack to be like a set of plates resting on top of one another. In the below diagram, you can't pick up plate #2 without also picking up plates #4 and #5 which rest on top of it.

██#4████ ██#5████
██#2█████████████ ██#3██████
██#1████████████████████████   (bottom)

Stock Git does not have strong support for dealing with non-linear commit stacks. For example, in stock Git, you can typically only rebase a linear stack like #2 + #4 onto a new destination, which would "abandon" #5. In git-branchless, commands like git move allow you to move a sub-stack like #2 + #4 + #5 as a group.


Bitemporality is the idea that data exists along two different timelines.

Stock Git has per-branch timelines, which indicates the order of commits which make up that branch. The git log command is used to show that timeline.

git-branchless adds support for per-commit timelines, which indicates how a commit was changed over time. This typically happens during local development, such as by running git commit --amend, which updates the current commit instead of making a new commit. This feature implements Mercurial's Changeset Evolution, and it powers novel features like git undo.

Stock Git has a limited version of per-commit timelines in the form of reflogs. However, these are inconvenient to use and insufficiently powerful for some use-cases. For technical details, see Comparison with the reflog.