Stacked Git logo

Stacked Git

stg(1)

NAME

stg - Manage stacks of patches using the Git content tracker

SYNOPSIS

stg [OPTIONS] <command> […​]
stg [OPTIONS] <-h|--help>
stg --version

DESCRIPTION

StGit (Stacked Git) is an application that provides a convenient way to maintain a patch stack on top of a Git branch:

  • The topmost (most recent) commits of a branch are given names. Such a named commit is called a patch.

  • After making changes to the worktree, you can incorporate the changes into an existing patch; this is called refreshing. You may refresh any patch, not just the topmost one.

  • You can pop a patch: temporarily putting it aside, so that the patch below it becomes the topmost patch. Later you may push it onto the stack again. Pushing and popping can be used to reorder patches.

  • You can easily rebase your patch stack on top of any other Git commit. (The base of a patch stack is the most recent Git commit that is not an StGit patch.) For example, if you started making patches on top of someone else’s branch, and that person publishes an updated branch, you can take all your patches and apply them on top of the updated branch.

  • As you would expect, changing what is below a patch can cause that patch to no longer apply cleanly — this can occur when you reorder patches, rebase patches, or refresh a non-topmost patch. StGit uses Git’s rename-aware three-way merge capability to automatically fix up what it can; if it still fails, it lets you manually resolve the conflict just like you would resolve a merge conflict in Git.

  • The patch stack is just some extra metadata attached to regular Git commits, so you can continue to use most Git tools along with StGit.

Typical uses

Tracking branch

Tracking changes from a remote branch, while maintaining local modifications against that branch, possibly with the intent of sending some patches upstream. You can modify your patch stack as much as you want, and when your patches are finally accepted upstream, the permanent recorded Git history will contain just the final sequence of patches, and not the messy sequence of edits that produced them.

Commands of interest in this workflow are e.g. rebase and mail.

Development branch

Even if you have no "upstream" to send patches to, you can use StGit as a convenient way to modify the recent history of a Git branch. For example, instead of first committing change A, then change B, and then A2 to fix A because it wasn’t quite right, you could incorporate the fix directly into A. This way of working results in a much more readable Git history than if you had immortalized every misstep you made on your way to the right solution.

Commands of interest in this workflow are e.g. uncommit, which can be used to move the patch stack base downwards — i.e., turn Git commits into StGit patches after the fact — and commit, its inverse.

For more information, see the tutorial.

Specifying patches

Many StGit commands take references to StGit patches as arguments. Patches in the stack are identified with short names, each of which must be unique in the stack.

Patches in the current branch are simply referred to by their name. Some commands allow you to specify a patch in another branch of the repository; this is done by prefixing the patch name with the branch name and a colon (e.g. otherbranch:thatpatch).

Commands that take multiple patch arguments may be supplied with patch ranges of the form patch1..patchN as an alternative to specifying each patch individually. For example, stg delete p0..p4 would be equivalent to stg delete p0 p1 p2 p3 p4. Patch ranges may be open on either or both ends. For example, stg delete ..p2 would delete the first applied patch up to and including patch p2. Alternatively, stg delete p2.. would delete patch p2 up to and including the topmost applied patch. And stg delete .. would delete all applied patches.

Specifying commits

Some StGit commands take Git commits as arguments. StGit accepts all commit expressions that Git does; and in addition, a patch name (optionally prefixed by a branch name and a colon) is allowed in this context. The usual Git modifiers ^ and ~ are also allowed; e.g., abranch:apatch~2 is the grandparent of the commit that is the patch apatch on branch abranch.

Instead of a patch name, you can say {base} to refer to the stack base (the commit just below the bottommost patch); so, abranch:{base} is the base of the stack in branch abranch.

If you need to pass a given StGit reference to a Git command, stg id will convert it to a Git commit id for you.

OPTIONS

The following generic option flags are available. Additional options are available for (and documented with) the different subcommands.

--version

Print version information

--help

Print help information.

-C

Run as if stg was started in <path> instead of the current working directory. When multiple -C options are given, each subsequent non-absolute -C <path> is interpreted relative to the preceding -C <path>.

This option affects arguments that expect path names or path specs in that their interpretations of the path names would be made relative to the working directory caused by the -C option.

--color <when>

Specify when to colorize the output.

auto (the default) enables colored output only when outputting to a terminal or TTY. The NO_COLOR environment variable is respected.

always and never unconditionlly enable/disable colored output, respectively.

ansi forces color to be output using ANSI escape sequences, even in a Windows console.

STGIT COMMANDS

We divide StGit commands in thematic groups, according to the primary type of object they create or change.

Patch Inspection

stg diff

Show a diff

stg files

Show files modified by a patch

stg id

Print git hash of a StGit revision

stg log

Display or optionally clear the stack changelog

stg show

Show patch commits

Patch Manipulation

stg edit

Edit a patch

stg fold

Fold diff file into the current patch

stg new

Create a new patch at top of the stack

stg refresh

Incorporate worktree changes into current patch

stg rename

Rename a patch

stg spill

Spill changes from the topmost patch

stg sync

Synchronize patches with a branch or a series

Stack Inspection

stg email

Format and send patches as email

stg export

Export patches to a directory

stg next

Print the name of the next patch

stg patches

Show patches that modify files

stg prev

Print the name of the previous patch

stg series

Display the patch series

stg top

Print the name of the top patch

Stack Manipulation

stg branch

Branch operations: switch, list, create, rename, delete, …​

stg clean

Delete empty patches from the series

stg commit

Finalize patches to the stack base

stg delete

Delete patches

stg float

Push patches to the top, even if applied

stg goto

Go to patch by pushing or popping as necessary

stg hide

Hide patches in the series

stg import

Import patches to stack

stg init

Initialize a StGit stack on current branch

stg pick

Import a patch from another branch or a commit object

stg pop

Pop (unapply) one or more applied patches

stg pull

Pull changes from a remote repository

stg push

Push (apply) one or more unapplied patches

stg rebase

Move the stack base to another point in history

stg redo

Undo the last undo operation

stg repair

Repair stack after branch is modified with git commands

stg reset

Reset the patch stack to an earlier state

stg sink

Move patches deeper in the stack

stg squash

Squash two or more patches into one

stg uncommit

Convert regular Git commits into StGit patches

stg undo

Undo the last command

stg unhide

Unhide hidden patches

Administration

stg completion

Support for shell completions

stg help

Print this message or the help of the given subcommand(s)

stg version

Print version information and exit

CONFIGURATION MECHANISM

StGit uses the same configuration mechanism as Git. See git(7) for more details.

TEMPLATES

A number of StGit commands make use of template files to provide useful default texts to be edited by the user. These <name>.tmpl template files are searched in the following directories:

  1. $GITDIR/ (in practice, the .git/ directory in your repository)

  2. $XDG_CONFIG_HOME/stgit/templates/

  3. $HOME/.stgit/templates/