Concepts

git-spice introduces a few concepts on top of Git. This section lists a few that are frequently used in the documentation.

Working with local branches

Branch

A regular Git branch. Branches can have a base: the branch they were created from. The branch currently checked out is called the current branch.

In the diagram, B is the current branch, and A is its base.

Trunk

The default branch of a repository. This is "main" or "master" in most repositories. Trunk is the only branch that does not have a base branch.

Stack

A stack is a collection of branches stacked on top of each other in a way that each branch except the trunk has a base branch.

In the diagram, A is stacked on top of trunk, B is stacked on top of A, and so on. A branch can have multiple branches stacked on top of it.

Downstack

Downstack refers to the branches below the current branch, all the way to, but not including, the trunk branch.

Upstack

Upstack refers to the branches stacked on top of the current branch, those branches' upstacks, and so on until no more branches remain. If a branch has multiple branches stacked on top of it, they are both upstack from it.

Sibling

A sibling to a branch is a branch that shares the same base branch. In the diagram, F is a sibling to B, and C is a sibling to D.

Restacking

Restacking is the process of rebasing the contents of a branch on top of its base branch, which it may have diverged from. This is done to keep the branch up-to-date with its base branch, and maintain a linear history.

Working with remote repositories

Change Request

Change Request refers to a single merge-able unit of work submitted to GitHub, GitLab, or Bitbucket. Each Change Request corresponds to a branch. On GitHub and Bitbucket, these are called Pull Requests, and on GitLab, they are called Merge Requests. Since git-spice supports all three platforms, the term Change Request is used to refer to all of them.

Upstream remote

The Git remote that hosts the trunk branch and receives Change Requests. Operations that pull trunk (e.g. gs repo sync) or manipulate Change Requests (e.g. gs branch submit) use the upstream remote.

In a same-repository workflow, the upstream remote and push remote are the same. In a fork workflow, the upstream remote points to the target repository, and the push remote points to your fork.

Push remote

The Git remote that receives submitted branch pushes. Operations that publish branch commits or inspect remote branch state use the push remote.

In a same-repository workflow, the upstream remote and push remote are the same. In a fork workflow, the upstream remote points to the target repository, and the push remote points to your fork.

Fork mode

Fork mode is enabled when the push remote and upstream remote differ. This may be used when you do not have write access to the target repository, and instead maintain a fork of the repository that you push branches to.

In fork mode, git-spice pushes branches to the push remote, and opens Change Requests against the upstream remote.

Change Requests are opened from the push remote to the upstream remote, only for branches that are based directly on trunk. Branches stacked on top of another local branch are still pushed to your fork, but git-spice does not create Change Requests for them.

See Fork Workflows for setup and workflow examples.