stg man page

stg — Manage stacks of patches using the Git content tracker

Synopsis

stg [--version | --help]
stg [--help <command> | <command> --help]
stg <command> [COMMAND OPTIONS] [ARGS]

Description

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

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[1].

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).

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(1) 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

Prints the StGit version, as well as version of other components used, such as Git and Python.

--help

Prints the synopsis and a list of all subcommands. If an StGit subcommand is given, prints the synposis for that subcommand.

Stgit Commands

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

Here is a short description of each command. A more detailed description is available in individual command manpages. Those manpages are named stg-<command>(1).

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. $HOME/.stgit/templates/

3. /usr/share/stgit/templates/

Notes

1.

the tutorial
[set $man.base.url.for.relative.links]/tutorial.html

Referenced By

stg-branch(1), stg-clean(1), stg-clone(1), stg-commit(1), stg-delete(1), stg-diff(1), stg-edit(1), stg-export(1), stg-files(1), stg-float(1), stg-fold(1), stg-goto(1), stg-hide(1), stg-id(1), stg-import(1), stg-init(1), stg-log(1), stg-mail(1), stg-new(1), stg-next(1), stg-patches(1), stg-pick(1), stg-pop(1), stg-prev(1), stg-publish(1), stg-pull(1), stg-push(1), stg-rebase(1), stg-redo(1), stg-refresh(1), stg-rename(1), stg-repair(1), stg-reset(1), stg-series(1), stg-show(1), stg-sink(1), stg-squash(1), stg-sync(1), stg-top(1), stg-uncommit(1), stg-undo(1), stg-unhide(1).

02/09/2018 StGit Manual