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 [OPTIONS] <command> [...]
       stg [OPTIONS] <-h|--help>
       stg --version

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
       Most StGit commands have patch arguments. Patches in the stack
       may be specified in a variety of ways. A patch in the current
       branch may simply referred to by its name, or, alternatively, be
       located by a relative offset from the topmost patch (e.g. +3), as
       an absolute index into the stack (e.g. 7), or as an offset from
       the last visible patch (e.g. ^1).

       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.

       The complete syntax for locating patches follows:

       <patchname>, e.g. patch
           The name of a patch.

       @
           Refers to the topmost applied patch, or the base of the stack
           if no patches are applied.

       [<patchname>]~[<n>], e.g. ~2, patch~, patch~3
           The <n>th previous patch from the named patch. If <patchname>
           is not supplied, @ is implied. A single ~ represents the
           first previous patch. Multiple ~ may be specified, e.g.
           patch~~~ is the same as patch~3. This is similar to git’s
           revision syntax where <rev>~[<n>] means the <n>th ancestor
           commit from <rev> following first parents.

       [<patchname>]+[<n>], e.g. +, +3, patch+, patch+3
           The <n>th next patch from the named patch. If <patchname> is
           not supplied, @ is implied. A single + represents the next
           patch in the series. Multiple + may be specified, e.g.
           patch+++ is the same as patch+3.

       -[<n>], e.g. -3, -
           References the <n>th previously applied patch. This is
           similar to ~<n>, except it is only valid without a patch name
           prefix. Note that certain commands with other options taking
           numeric values may require escaping - with \-, e.g.  \-10.

       <n>, e.g. 3
           The patch at absolute index <n> in the stack. This is a
           zero-based index, so 0 refers to the bottommost patch in the
           stack.

       ^[<n>], e.g. ^, ^3
           The patch at offset <n> from the last visible patch in the
           stack. This is a zero-based offset, so ^0 refers to the last
           visible patch in the stack, which is equivalent to just ^.
           Negative values of <n> are allowed and refer to hidden
           patches which are after the last visible patch in the stack.

       {base}+[<n>], e.g. {base}+, {base}+3
           The patch at offset <n> from the stack’s base commit. Since
           the stack base is not a commit, a positive offset is
           required.

       Take note that numeric patch locations of the form <n>, -<n>, and
       +<n>, e.g. 3, -3, or +3 are also valid patch names. I.e. it is
       possible (but not recommended) to name a patch, for example,
       "-3". In the case where a patch name could also be interpreted as
       a numeric index or offset, the literal patch name will take
       precidence when resolving the patch location.

   Specifying commits
       Some StGit commands take Git commits as arguments. StGit accepts
       all revision specifications that Git does (see gitrevisions(7));
       and additionally, the patch specifiers from above. The usual Git
       modifiers, including ^, are also allowed; e.g.
       some-branch:a-patch^^ refers to the grandparent of the commit
       that is patch a-patch on branch some-branch.

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

   Patch Inspection
       stg-diff(1)
           Show a diff

       stg-files(1)
           Show files modified by a patch

       stg-id(1)
           Print git hash of a StGit revision

       stg-log(1)
           Display or optionally clear the stack changelog

       stg-show(1)
           Show patch commits

   Patch Manipulation
       stg-edit(1)
           Edit a patch

       stg-fold(1)
           Fold diff file into the current patch

       stg-new(1)
           Create a new patch at top of the stack

       stg-refresh(1)
           Incorporate worktree changes into current patch

       stg-rename(1)
           Rename a patch

       stg-spill(1)
           Spill changes from the topmost patch

       stg-sync(1)
           Synchronize patches with a branch or a series

   Stack Inspection
       stg-email(1)
           Format and send patches as email

       stg-export(1)
           Export patches to a directory

       stg-next(1)
           Print the name of the next patch

       stg-patches(1)
           Show patches that modify files

       stg-prev(1)
           Print the name of the previous patch

       stg-series(1)
           Display the patch series

       stg-top(1)
           Print the name of the top patch

   Stack Manipulation
       stg-branch(1)
           Branch operations: switch, list, create, rename, delete, ...

       stg-clean(1)
           Delete empty patches from the series

       stg-commit(1)
           Finalize patches to the stack base

       stg-delete(1)
           Delete patches

       stg-float(1)
           Push patches to the top, even if applied

       stg-goto(1)
           Go to patch by pushing or popping as necessary

       stg-hide(1)
           Hide patches in the series

       stg-import(1)
           Import patches to stack

       stg-init(1)
           Initialize a StGit stack on a branch

       stg-pick(1)
           Import a patch from another branch or a commit object

       stg-pop(1)
           Pop (unapply) one or more applied patches

       stg-pull(1)
           Pull changes from a remote repository

       stg-push(1)
           Push (apply) one or more unapplied patches

       stg-rebase(1)
           Move the stack base to another point in history

       stg-redo(1)
           Undo the last undo operation

       stg-repair(1)
           Repair stack after branch is modified with git commands

       stg-reset(1)
           Reset the patch stack to an earlier state

       stg-sink(1)
           Move patches deeper in the stack

       stg-squash(1)
           Squash two or more patches into one

       stg-uncommit(1)
           Convert regular Git commits into StGit patches

       stg-undo(1)
           Undo the last command

       stg-unhide(1)
           Unhide hidden patches

   Administration
       stg-completion(1)
           Support for shell completions

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

       stg-version(1)
           Print version information and exit

CONFIGURATION MECHANISM         top

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

   Variables
       branch.<name>.stgit.autostash, branch.<name>.stgit.fetchcmd,
       branch.<name>.stgit.pull-policy, branch.<name>.stgit.pullcmd,
       branch.<name>.stgit.rebasecmd
           Branch-specific configuration values. These take precedence
           over the corresponding non-branch specific configuration
           values (see below).

       branch.<name>.stgit.parentbranch
           Specifies the parent branch of a branch with a StGit stack.
           This value is set by stg-branch(1) when creating or cloning
           branches, and not typically set by the user. The parent
           branch is used by stg-pull(1) when stgit.pull-policy is
           either rebase or fetch-rebase to determine the target of the
           rebase.

       stgit.alias.*
           Command aliases for stg. For example, after defining
           stgit.alias.list = series -d, running stg list is equivalent
           to stg series -d. Arguments are split by spaces and the usual
           shell quoting and escaping is supported. A quote pair or
           backslash may be used to quote them.

           If the alias expansion is prefixed with an exclamation point
           (!), it will be treated as a shell command. For example,
           defining stgit.alias.outgoing = !git log @{u}, running stg
           outgoing is equivalent to running the shell command git log
           @{u}. Note that shell commands will be executed from the
           top-level directory of the working tree, which may not
           necessarily be the current directory.  GIT_PREFIX is set as
           returned by running git rev-parse --show-prefix from the
           original current directory. See git-rev-parse(1).

           Aliases that would hide existing StGit commands are ignored.

       stgit.autoimerge
           When set to true, if conflicts occur when pushing a patch,
           git-mergetool(1) is automatically run to attempt to resolve
           the conflicts.

       stgit.autosign
           Automatically add "Signed-off-by:" trailer to commit messages
           for new patches created with stg-new(1) or lingstg:import[].

       stgit.autostash
           When running stg-rebase(1), if any modified files are found
           in the working tree, a temporary stash is created with
           git-stash(1) before the operation begins and is applied after
           the operation completes.

       stgit.diff-opts
           Options to pass-through to git diff-tree for stg-diff(1),
           stg-export(1), stg-patches(1), and stg-show(1). Multiple
           space-separated options may be specified. See
           git-diff-tree(1) for information about the various available
           options.

       stgit.edit.verbose
           When set to true, the patch’s diff will be shown when
           interactively editing a patch description with, for example,
           stg-edit(1).

       stgit.editor
           Commands such as stg-edit(1) and stg-new(1) open an editor to
           edit the patch description and commit message. The editor set
           by this variable is launched when the GIT_EDITOR environment
           variable is not set. This variable takes precedence over the
           core.editor configuration variable as well as the VISUAL and
           EDITOR environment variables.

       stgit.fetchcmd
           The command specified by this variable will be run by
           stg-pull(1) to fetch from the remote repository when
           stgit.pull-policy is fetch-rebase. When not set, the default
           command is git fetch.

       stgit.gpgsign
           A boolean to specify whether StGit stack metadata commits
           should be GPG signed.

           N.B. Set commit.gpgsign to determine whether patch commits
           themselves are GPG signed. See git-config(1) for more
           information about commit.gpgsign.

       stgit.import.message-id
           When set to true, create Message-ID: trailer in the patch
           description of patches imported from email using
           stg-import(1).

       stgit.keepoptimized
           When set to true, after pulling changes with stg-pull(1), the
           repository’s object database will be optimized by running
           git-repack(1).

       stgit.namelength
           An integer used to determine the maximum length, in
           characters, of automatically generated patch names. The
           default value is 30. This option does not affect
           user-specified patch names. Setting to a value less than or
           equal to 0 will allow automatically generated patch names of
           unlimited length.

           Automatically generated patch names are truncated at word
           boundaries less than or equal to the value of
           stgit.namelength. As a result, patch names will typically not
           be truncated at exactly this number of characters. It is also
           possible for automatically generated patch names to be longer
           than this value if a work boundary cannot be found within
           this bound, or if additional characters need to be added to
           the patch name to make it unique.

       stgit.pick.expose-format
           Format of the commit message for patches picked using the
           --expose option with stg-pick(1). The value of this option is
           as may be specified to the --pretty option of git-show(1).
           The default is format:%B%n(imported from commit %H).

       stgit.pull-policy
           Policy used by stg-pull(1) for pulling changes from a remote
           repository. Valid values include:

           •   pull, the default, uses git-pull(1) or stgit.pullcmd, if
               set, to pull changes from the remote repository.

           •   rebase uses git-reset(1) or stgit.rebasecmd, if set, to
               rebase the patch stack before reapplying patches.

           •   fetch-rebase first fetches commits from the remote
               repository using git-fetch(1) or stgit.fetchcmd, if set,
               before performing the rebase as described above.

       stgit.pullcmd
           The command to be run by stg-pull(1) to pull changes from the
           remote repository when stgit.pull-policy is pull (the
           default). The default value is git pull.

       stgit.push.allow-conflicts
           A boolean to specify whether stg-push(1) and other commands
           that push patches will push patches that may result in merge
           conflicts. The default is true, which means that a patch with
           conflicts will be pushed and if the conflicts cannot be
           automatically resolved, the operation will stop and with the
           conflicts left to be resolved manually.

           When set to false, a patch that would have merge conflicts
           will not be pushed, thus leaving the stack on the last patch
           that could be pushed without conflicts.

           This configuration variable may be overridden on the command
           line with either --conflicts[=allow] or --conflicts=disallow.

           N.B.: stgit.autoimerge only has an affect when push conflicts
           are allowed.

       stgit.rebasecmd
           The command to be run by stg-pull(1) to set the new stack
           base when stgit.pull-policy is either rebase or fetch-rebase.
           The default is git reset --hard.

       stgit.refreshsubmodules
           A boolean to specify whether stg-refresh(1) includes
           submodules in patch content. This value may be overridden by
           the --submodules or --no-submodules option to stg-refresh(1).
           By default, submodule content is not included in patch
           content.

       stgit.shortnr
           The number of patches listed by stg-series(1) when the
           -s/--short option is specified. Defaults to 5.

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

        3. $HOME/.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
       ⟨https://github.com/stacked-git/stgit.git⟩ on 2024-06-14.  (At
       that time, the date of the most recent commit that was found in
       the repository was 2024-05-22.)  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
       [email protected]

StGit 2.4.7                    06/14/2024                         STG(1)

Pages that refer to this page: stg-branch(1)stg-clean(1)stg-commit(1)stg-completion(1)stg-delete(1)stg-diff(1)stg-edit(1)stg-email(1)stg-export(1)stg-files(1)stg-float(1)stg-fold(1)stg-goto(1)stg-help(1)stg-hide(1)stg-id(1)stg-import(1)stg-init(1)stg-log(1)stg-new(1)stg-next(1)stg-patches(1)stg-pick(1)stg-pop(1)stg-prev(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-spill(1)stg-squash(1)stg-sync(1)stg-top(1)stg-uncommit(1)stg-undo(1)stg-unhide(1)stg-version(1)