Documentation/stg.txt

   1 stg(1)
   2 ======
   3 Yann Dirson <ydirson@altern.org>
   4
   5 NAME
   6 ----
   7 stg - Manage stacks of patches using the Git content tracker
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'stg' [--version | --help]
  13 'stg' [--help <command> | <command> --help]
  14 'stg' <command> [COMMAND OPTIONS] [ARGS]
  15
  16 DESCRIPTION
  17 -----------
  18
  19 StGit (Stacked Git) is an application that provides a convenient way
  20 to maintain a 'patch stack' on top of a Git branch:
  21
  22   * The topmost (most recent) commits of a branch are given names.
  23     Such a named commit is called a 'patch'.
  24
  25   * After making changes to the worktree, you can incorporate the
  26     changes into an existing patch; this is called 'refreshing'. You
  27     may refresh any patch, not just the topmost one.
  28
  29   * You can 'pop' a patch: temporarily putting it aside, so that the
  30     patch below it becomes the topmost patch. Later you may 'push' it
  31     onto the stack again. Pushing and popping can be used to reorder
  32     patches.
  33
  34   * You can easily 'rebase' your patch stack on top of any other Git
  35     commit. (The 'base' of a patch stack is the most recent Git commit
  36     that is not an StGit patch.) For example, if you started making
  37     patches on top of someone else's branch, and that person publishes
  38     an updated branch, you can take all your patches and apply them on
  39     top of the updated branch.
  40
  41   * As you would expect, changing what is below a patch can cause that
  42     patch to no longer apply cleanly -- this can occur when you
  43     reorder patches, rebase patches, or refresh a non-topmost patch.
  44     StGit uses Git's rename-aware three-way merge capability to
  45     automatically fix up what it can; if it still fails, it lets you
  46     manually resolve the conflict just like you would resolve a merge
  47     conflict in Git.
  48
  49   * The patch stack is just some extra metadata attached to regular
  50     Git commits, so you can continue to use most Git tools along with
  51     StGit.
  52
  53 Typical uses
  54 ~~~~~~~~~~~~
  55
  56 Tracking branch::
  57
  58   Tracking changes from a remote branch, while maintaining local
  59   modifications against that branch, possibly with the intent of
  60   sending some patches upstream. You can modify your patch stack as
  61   much as you want, and when your patches are finally accepted
  62   upstream, the permanent recorded Git history will contain just the
  63   final sequence of patches, and not the messy sequence of edits that
  64   produced them.
  65 +
  66 Commands of interest in this workflow are e.g. linkstgsub:rebase[] and
  67 linkstgsub:mail[].
  68
  69 Development branch::
  70
  71   Even if you have no "upstream" to send patches to, you can use StGit
  72   as a convenient way to modify the recent history of a Git branch.
  73   For example, instead of first committing change 'A', then change
  74   'B', and then 'A2' to fix 'A' because it wasn't quite right, you
  75   could incorporate the fix directly into 'A'. This way of working
  76   results in a much more readable Git history than if you had
  77   immortalized every misstep you made on your way to the right
  78   solution.
  79 +
  80 Commands of interest in this workflow are e.g. linkstgsub:uncommit[],
  81 which can be used to move the patch stack base downwards -- i.e., turn
  82 Git commits into StGit patches after the fact -- and
  83 linkstgsub:commit[], its inverse.
  84
  85 For more information, see the
  86 https://stacked-git.github.io/guides/tutorial[tutorial].
  87
  88 Specifying patches
  89 ~~~~~~~~~~~~~~~~~~
  90
  91 Many StGit commands take references to StGit patches as arguments.
  92 Patches in the stack are identified with short names, each of which
  93 must be unique in the stack.
  94
  95 Patches in the current branch are simply referred to by their name.
  96 Some commands allow you to specify a patch in another branch of the
  97 repository; this is done by prefixing the patch name with the branch
  98 name and a colon (e.g. +otherbranch:thatpatch+).
  99
 100 Specifying commits
 101 ~~~~~~~~~~~~~~~~~~
 102
 103 Some StGit commands take Git commits as arguments. StGit accepts all
 104 commit expressions that Git does; and in addition, a patch name
 105 (optionally prefixed by a branch name and a colon) is allowed in this
 106 context. The usual Git modifiers $$^$$ and $$~$$ are also allowed;
 107 e.g., +abranch:apatch~2+ is the grandparent of the commit that is the
 108 patch +apatch+ on branch +abranch+.
 109
 110 Instead of a patch name, you can say +$${base}$$+ to refer to the
 111 stack base (the commit just below the bottommost patch); so,
 112 +abranch:$${base}$$+ is the base of the stack in branch +abranch+.
 113
 114 If you need to pass a given StGit reference to a Git command,
 115 linkstg:id[] will convert it to a Git commit id for you.
 116
 117 OPTIONS
 118 -------
 119
 120 The following generic option flags are available. Additional options
 121 are available for (and documented with) the different subcommands.
 122
 123 --version::
 124   Prints the StGit version, as well as version of other components
 125   used, such as Git and Python.
 126
 127 --help::
 128   Prints the synopsis and a list of all subcommands. If an StGit
 129   subcommand is given, prints the synposis for that subcommand.
 130
 131 STGIT COMMANDS
 132 --------------
 133
 134 We divide StGit commands in thematic groups, according to the primary
 135 type of object they create or change.
 136
 137 ifdef::backend-docbook[]
 138 Here is a short description of each command. A more detailed
 139 description is available in individual command manpages.  Those
 140 manpages are named 'stg-<command>(1)'.
 141 endif::backend-docbook[]
 142
 143 include::command-list.txt[]
 144
 145 CONFIGURATION MECHANISM
 146 -----------------------
 147
 148 StGit uses the same configuration mechanism as Git. See linkgit:git[7]
 149 for more details.
 150
 151 TEMPLATES
 152 ---------
 153
 154 A number of StGit commands make use of template files to provide
 155 useful default texts to be edited by the user. These +<name>.tmpl+
 156 template files are searched in the following directories:
 157
 158   . +$GITDIR/+ (in practice, the +.git/+ directory in your repository)
 159   . +$HOME/.stgit/templates/+
 160   . +/usr/share/stgit/templates/+