stg(1)
======
Yann Dirson <ydirson@altern.org>

NAME
----
stg - Manage stacks of patches using the Git content tracker

SYNOPSIS
--------
[verse]
'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. linkstgsub:rebase[] and
linkstgsub: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. linkstgsub:uncommit[],
which can be used to move the patch stack base downwards -- i.e., turn
Git commits into StGit patches after the fact -- and
linkstgsub:commit[], its inverse.

For more information, see the
https://stacked-git.github.io/guides/tutorial[tutorial].

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. +{plus}3+), as an
absolute index into the stack (e.g. +7+), or as an offset from the
last visible patch (e.g. +{caret}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>]{tilde}[<n>]', e.g. '{tilde}2', 'patch{tilde}', 'patch{tilde}3'::
  The <n>th previous patch from the named patch. If <patchname> is not
  supplied, '@' is implied. A single '{tilde}' represents the first
  previous patch. Multiple '{tilde}' may be specified, e.g.
  'patch{tilde}{tilde}{tilde}' is the same as 'patch{tilde}3'. This is
  similar to git's revision syntax where '<rev>~[<n>]' means the <n>th
  ancestor commit from <rev> following first parents.

'[<patchname>]{plus}[<n>]', e.g. '{plus}', '{plus}3', 'patch{plus}', 'patch{plus}3'::
  The <n>th next patch from the named patch. If <patchname> is not
  supplied, '@' is implied. A single '{plus}' represents the next
  patch in the series. Multiple '{plus}' may be specified, e.g.
  'patch{plus}{plus}{plus}' is the same as 'patch{plus}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.

'{caret}[<n>]', e.g. '{caret}', '{caret}3'::
  The patch at offset <n> from the last visible patch in the stack.
  This is a zero-based offset, so '{caret}0' refers to the last
  visible patch in the stack, which is equivalent to just
  '{caret}'. 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 linkgit: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,
linkstg:id[] 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.

ifdef::backend-docbook[]
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)'.
endif::backend-docbook[]

include::command-list.txt[]

CONFIGURATION MECHANISM
-----------------------

StGit uses the same configuration mechanism as Git. See linkgit: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
  linkstg:branch[] when creating or cloning branches, and not typically set by the user.
  The parent branch is used by linkstg:pull[] 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
linkgit: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, linkgit: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 linkstg:new[] 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 linkstg:rebase[], if any modified files are found in the working tree, a
  temporary stash is created with linkgit: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 linkstg:diff[], linkstg:export[],
  linkstg:patches[], and linkstg:show[]. Multiple space-separated options may be
  specified. See linkgit: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, linkstg:edit[].

stgit.editor::
  Commands such as linkstg:edit[] and linkstg:new[] 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 linkstg:pull[] 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 linkgit: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 linkstg:import[].

stgit.keepoptimized::
  When set to 'true', after pulling changes with linkstg:pull[], the repository's object
  database will be optimized by running linkgit: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
  linkstg:pick[]. The value of this option is as may be specified to the '--pretty'
  option of linkgit:git-show[1]. The default is 'format:%B%n(imported from commit %H)'.

stgit.pull-policy::
  Policy used by linkstg:pull[] for pulling changes from a remote repository. Valid
  values include:
+
* `pull`, the default, uses linkgit:git-pull[1] or 'stgit.pullcmd', if set, to pull
  changes from the remote repository.
* `rebase` uses linkgit: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
  linkgit:git-fetch[1] or 'stgit.fetchcmd', if set, before performing the rebase as
  described above.

stgit.pullcmd::
  The command to be run by linkstg:pull[] 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 linkstg:push[] 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 linkstg:pull[] 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 linkstg:refresh[] includes submodules in patch content.
  This value may be overridden by the '--submodules' or '--no-submodules' option to
  linkstg:refresh[]. By default, submodule content is not included in patch content.

stgit.shortnr::
  The number of patches listed by linkstg:series[] 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:

  . +$GITDIR/+ (in practice, the +.git/+ directory in your repository)
  . +$XDG_CONFIG_HOME/stgit/templates/+
  . +$HOME/.stgit/templates/+
