# stg

## 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******[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



           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.
    
           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-name(1)
               Print patch name of a StGit revision
    
           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



           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 signoff trailer to commit messages for new
               patches created with stg-new(1) or lingstg:import[]. The value
               of this configuration variable will be used as the key of the
               trailer and therefore should be set to something like
               _Signed-off-by_.
    
           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



           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



            1. tutorial
               https://stacked-git.github.io/guides/tutorial
    


* * *