stg(1) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | STGIT COMMANDS | CONFIGURATION MECHANISM | TEMPLATES | NOTES | COLOPHON

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

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

CONFIGURATION MECHANISM         top

       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. tutorial
           https://stacked-git.github.io/guides/tutorial

COLOPHON         top

       This page is part of the stgit (Stacked Git) project.
       Information about the project can be found at 
       ⟨http://www.procode.org/stgit/⟩.  If you have a bug report for
       this manual page, see ⟨http://www.procode.org/stgit/⟩.  This page
       was obtained from the project's upstream Git repository
       ⟨http://repo.or.cz/stgit.git⟩ on 2021-04-01.  (At that time, the
       date of the most recent commit that was found in the repository
       was 2021-02-15.)  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
       man-pages@man7.org

StGit                          04/01/2021                         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)