Documentation/stg.txt

   1 stg(1)
   2 ======
   3 Yann Dirson <ydirson@altern.org>
   4 v0.12.1, February 2007
   5
   6 NAME
   7 ----
   8 stg - manage stacks of patches using the GIT content tracker
   9
  10 SYNOPSIS
  11 --------
  12 [verse]
  13 'stg' [--version | --help]
  14 'stg' [--help <command> | <command> --help]
  15 'stg' <command> [COMMAND OPTIONS] [ARGS]
  16
  17 DESCRIPTION
  18 -----------
  19
  20 StGIT (Stacked GIT) is an application providing similar functionality
  21 to Quilt (i.e. pushing/popping patches to/from a stack), on top of
  22 GIT. These operations are performed using GIT commands and the patches
  23 are stored as GIT commit objects, allowing easy merging of the StGIT
  24 patches into other repositories using standard GIT functionality.
  25
  26 An StGIT stack is a GIT branch with additional information to help
  27 making changes to individual patches you already committed, rather
  28 than making changes by adding new commits.  It is thus a
  29 non-forwarding, or rewinding branch: the old head of the branch is
  30 often not reachable as one of the new head's ancestors.
  31
  32 Typical uses of StGIT include:
  33
  34 Tracking branch::
  35         Tracking changes from a remote branch, while maintaining local
  36         modifications against that branch, possibly with the intent of
  37         sending some patches upstream.  StGIT assists in preparing and
  38         cleaning up patches until they are acceptable upstream, as
  39         well as maintaining local patches not meant to be sent
  40         upstream.
  41 +
  42 In such a setup, typically all commits on your branch are StGIT
  43 patches; the stack base is the branch point where your changes "fork"
  44 off their parent branch.
  45
  46 Development branch::
  47         Preparing and testing your commits before publishing them,
  48         separating your features from unrelated bugfixes collected
  49         while developping.
  50 +
  51 In such a setup, not all commits on your branch need to be StGIT
  52 patches; there may be regular GIT commits below your stack base.
  53
  54 OPTIONS
  55 -------
  56
  57 The following generic option flags are available.  Additional options
  58 are available per-command, and documented in the command-specific
  59 documentation.
  60
  61 --version::
  62         Prints the StGIT suite version that the 'stg' program came
  63         from, as well as version of other components used, such as GIT
  64         and Python.
  65
  66 --help::
  67         Prints the synopsis and a list of all commands.  If a git
  68         command is given this option will display the specific help
  69         for that command.
  70
  71 STGIT COMMANDS
  72 --------------
  73
  74 We divide StGIT commands in thematic groups, according to the primary
  75 type of object they create or change.
  76
  77 ifdef::backend-docbook[]
  78 Here is a short description of each command. A more detailed
  79 description is available in individual command manpages.  Those
  80 manpages are named 'stg-<command>(1)'.
  81 endif::backend-docbook[]
  82
  83 Generic commands
  84 ~~~~~~~~~~~~~~~~
  85
  86 User-support commands not touching the repository.
  87
  88 stg help::
  89         stgdesc:help[]
  90 stg version::
  91         stgdesc:version[]
  92 stg copyright::
  93         stgdesc:copyright[]
  94
  95 Repository commands
  96 ~~~~~~~~~~~~~~~~~~~
  97
  98 stglink:clone[]::
  99         stgdesc:clone[]
 100 stglink:id[]::
 101         stgdesc:id[]
 102
 103 Stack commands
 104 ~~~~~~~~~~~~~~
 105
 106 Stack management
 107 ^^^^^^^^^^^^^^^^
 108
 109 stglink:branch[]::
 110         stgdesc:branch[]
 111 stglink:init[]::
 112         stgdesc:init[]
 113 stglink:clean[]::
 114         stgdesc:clean[]
 115 stglink:pull[]::
 116         stgdesc:pull[]
 117 stglink:rebase[]::
 118         stgdesc:rebase[]
 119
 120 stglink:commit[]::
 121         stgdesc:commit[]
 122 stglink:uncommit[]::
 123         stgdesc:uncommit[]
 124 stglink:assimilate[]::
 125         stgdesc:assimilate[]
 126
 127 Controlling what patches are applied
 128 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 129
 130 stglink:series[]::
 131         stgdesc:series[]
 132 stglink:push[]::
 133         stgdesc:push[]
 134 stglink:pop[]::
 135         stgdesc:pop[]
 136 stglink:goto[]::
 137         stgdesc:goto[]
 138 stglink:float[]::
 139         stgdesc:float[]
 140 stglink:bury[]::
 141         stgdesc:bury[]
 142 stglink:applied[]::
 143         stgdesc:applied[]
 144 stglink:unapplied[]::
 145         stgdesc:unapplied[]
 146 stglink:top[]::
 147         stgdesc:top[]
 148
 149 stglink:hide[]::
 150         stgdesc:hide[]
 151 stglink:unhide[]::
 152         stgdesc:unhide[]
 153
 154 Miscellaneous stack commands
 155 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 156
 157 stglink:patches[]::
 158         stgdesc:patches[]
 159
 160
 161 Patch commands
 162 ~~~~~~~~~~~~~~
 163
 164 Patch management
 165 ^^^^^^^^^^^^^^^^
 166
 167 stglink:new[]::
 168         stgdesc:new[]
 169 stglink:delete[]::
 170         stgdesc:delete[]
 171 stglink:rename[]::
 172         stgdesc:rename[]
 173 stglink:log[]::
 174         stgdesc:log[]
 175
 176 Controlling patch contents
 177 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 178
 179 stglink:files[]::
 180         stgdesc:files[]
 181 stglink:show[]::
 182         stgdesc:show[]
 183 stglink:refresh[]::
 184         stgdesc:refresh[]
 185 stglink:fold[]::
 186         stgdesc:fold[]
 187 stglink:pick[]::
 188         stgdesc:pick[]
 189 stglink:sync[]::
 190         stgdesc:sync[]
 191
 192 Interaction with the rest of the world
 193 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 194
 195 stglink:export[]::
 196         stgdesc:export[]
 197 stglink:import[]::
 198         stgdesc:import[]
 199 stglink:mail[]::
 200         stgdesc:mail[]
 201
 202
 203 Working-copy commands
 204 ~~~~~~~~~~~~~~~~~~~~~
 205
 206 stglink:add[]::
 207         stgdesc:add[]
 208 stglink:rm[]::
 209         stgdesc:rm[]
 210 stglink:cp[]::
 211         stgdesc:cp[]
 212 stglink:status[]::
 213         stgdesc:status[]
 214 stglink:diff[]::
 215         stgdesc:diff[]
 216 stglink:resolved[]::
 217         stgdesc:resolved[]
 218
 219 CONFIGURATION MECHANISM
 220 -----------------------
 221
 222 Starting with 0.12, StGIT uses the same configuration mechanism as
 223 GIT.  See gitlink:git[7] for more details.
 224
 225 TEMPLATES
 226 ---------
 227
 228 A number of StGIT commands make use of template files to provide
 229 useful default texts to be edited by the user.  These '<name>.tmpl'
 230 template files are searched in the following directories:
 231
 232         $GITDIR/
 233         $HOME/.stgit/templates/
 234         /usr/share/stgit/templates/