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:applied[]::
 141         stgdesc:applied[]
 142 stglink:unapplied[]::
 143         stgdesc:unapplied[]
 144 stglink:top[]::
 145         stgdesc:top[]
 146
 147 stglink:hide[]::
 148         stgdesc:hide[]
 149 stglink:unhide[]::
 150         stgdesc:unhide[]
 151
 152 Miscellaneous stack commands
 153 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 154
 155 stglink:patches[]::
 156         stgdesc:patches[]
 157
 158
 159 Patch commands
 160 ~~~~~~~~~~~~~~
 161
 162 Patch management
 163 ^^^^^^^^^^^^^^^^
 164
 165 stglink:new[]::
 166         stgdesc:new[]
 167 stglink:delete[]::
 168         stgdesc:delete[]
 169 stglink:rename[]::
 170         stgdesc:rename[]
 171 stglink:log[]::
 172         stgdesc:log[]
 173
 174 Controlling patch contents
 175 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 176
 177 stglink:files[]::
 178         stgdesc:files[]
 179 stglink:show[]::
 180         stgdesc:show[]
 181 stglink:refresh[]::
 182         stgdesc:refresh[]
 183 stglink:fold[]::
 184         stgdesc:fold[]
 185 stglink:pick[]::
 186         stgdesc:pick[]
 187 stglink:sync[]::
 188         stgdesc:sync[]
 189
 190 Interaction with the rest of the world
 191 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 192
 193 stglink:export[]::
 194         stgdesc:export[]
 195 stglink:import[]::
 196         stgdesc:import[]
 197 stglink:mail[]::
 198         stgdesc:mail[]
 199
 200
 201 Working-copy commands
 202 ~~~~~~~~~~~~~~~~~~~~~
 203
 204 stglink:add[]::
 205         stgdesc:add[]
 206 stglink:rm[]::
 207         stgdesc:rm[]
 208 stglink:cp[]::
 209         stgdesc:cp[]
 210 stglink:status[]::
 211         stgdesc:status[]
 212 stglink:diff[]::
 213         stgdesc:diff[]
 214 stglink:resolved[]::
 215         stgdesc:resolved[]
 216
 217 CONFIGURATION MECHANISM
 218 -----------------------
 219
 220 Starting with 0.12, StGIT uses the same configuration mechanism as
 221 GIT.  See gitlink:git[7] for more details.
 222
 223 TEMPLATES
 224 ---------
 225
 226 A number of StGIT commands make use of template files to provide
 227 useful default texts to be edited by the user.  These '<name>.tmpl'
 228 template files are searched in the following directories:
 229
 230         $GITDIR/
 231         $HOME/.stgit/templates/
 232         /usr/share/stgit/templates/