STG(1)                          StGit Manual                          STG(1)

NAME         top

       stg - Manage stacks of patches using the Git content tracker

SYNOPSIS         top

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

DESCRIPTION         top

       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

       ·   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

   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

           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
       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         top

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

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

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

STGIT COMMANDS         top

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

   Repository commands
           Make a local clone of a remote repository

           Print the git hash value of a StGit reference

   Stack (branch) commands
           Branch operations: switch, list, create, rename, delete, ...

           Delete the empty patches in the series

           Permanently store the applied patches into the stack base

           Push patches to the top, even if applied

           Push or pop patches to the given one

           Hide a patch in the series

           Initialise the current branch for use with StGIT

           Display the patch changelog

           Print the name of the next patch

           Show the applied patches modifying a file

           Pop one or more patches from the stack

           Print the name of the previous patch

           Push the stack changes to a merge-friendly branch

           Pull changes from a remote repository

           Push one or more patches onto the stack

           Move the stack base to another point in history

           Undo the last undo operation

           Fix StGit metadata if branch was modified with git commands

           Reset the patch stack to an earlier state

           Print the patch series

           Send patches deeper down the stack

           Squash two or more patches into one

           Print the name of the top patch

           Turn regular git commits into StGit patches

           Undo the last operation

           Unhide a hidden patch

   Patch commands
           Delete patches

           Edit a patch description or diff

           Export patches to a directory

           Show the files modified by a patch (or the current patch)

           Integrate a GNU diff patch into the current patch

           Import a GNU diff file as a new patch

           Send a patch or series of patches by e-mail

           Create a new, empty patch

           Import a patch from a different branch or a commit object

           Generate a new commit for the current patch

           Rename a patch

           Show the commit corresponding to a patch

           Synchronise patches with a branch or a series

   Index/worktree commands
           Show the tree diff


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

TEMPLATES         top

       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         top

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

COLOPHON         top

       This page is part of the stgit (Stacked Git) project.  Information
       about the project can be found at ⟨⟩.
       If you have a bug report for this manual page, see
       ⟨⟩.  This page was obtained from the
       project's upstream Git repository ⟨⟩ on
       2017-11-25.  (At that time, the date of the most recent commit that
       was found in the repository was 2017-10-14.)  If you discover any
       rendering problems in this HTML version of the page, or you believe
       there is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

StGit                            11/25/2017                           STG(1)

Pages that refer to this page: 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)