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 Patches
  55 ~~~~~~~
  56
  57 Many StGIT commands take references to StGIT patches as arguments.
  58 Patches in the stack are identified with short names, each of which
  59 must be unique in the stack.
  60
  61 Patches in the current stack are just referred to by their name.  Some
  62 commands allow you to specify a patch in another stack of the repository;
  63 this is done by suffixing the patch name with an '@' sign followed by the
  64 branch name (eg. 'thispatch@otherbranch').
  65
  66 A number of positions in the stack related to the patch are also
  67 accessible through '//' suffixes.  For example, 'patch//top' is
  68 equivalent to 'patch', and 'patch//bottom' refers to the commit below
  69 'patch' (i.e. the patch below, or the stack base if this is the
  70 bottom-most patch).  Similarly '//top.old' and '//bottom.old'
  71 refer to the previous version of the patch (before the last
  72 stglink:push[] or stglink:refresh[] operation).  When referring to the
  73 current patch, its name can be omitted (eg. 'currentpatch//bottom.old'
  74 can be abbreviated as 'bottom.old').
  75
  76 If you need to pass a given StGIT reference to a git command,
  77 stglink:id[] will convert it to a git commit id.
  78
  79 OPTIONS
  80 -------
  81
  82 The following generic option flags are available.  Additional options
  83 are available per-command, and documented in the command-specific
  84 documentation.
  85
  86 --version::
  87         Prints the StGIT suite version that the 'stg' program came
  88         from, as well as version of other components used, such as GIT
  89         and Python.
  90
  91 --help::
  92         Prints the synopsis and a list of all commands.  If a git
  93         command is given this option will display the specific help
  94         for that command.
  95
  96 STGIT COMMANDS
  97 --------------
  98
  99 We divide StGIT commands in thematic groups, according to the primary
 100 type of object they create or change.
 101
 102 ifdef::backend-docbook[]
 103 Here is a short description of each command. A more detailed
 104 description is available in individual command manpages.  Those
 105 manpages are named 'stg-<command>(1)'.
 106 endif::backend-docbook[]
 107
 108 Generic commands
 109 ~~~~~~~~~~~~~~~~
 110
 111 User-support commands not touching the repository.
 112
 113 stg help::
 114         stgdesc:help[]
 115 stg version::
 116         stgdesc:version[]
 117 stg copyright::
 118         stgdesc:copyright[]
 119
 120 Repository commands
 121 ~~~~~~~~~~~~~~~~~~~
 122
 123 stglink:clone[]::
 124         stgdesc:clone[]
 125 stglink:id[]::
 126         stgdesc:id[]
 127
 128 Stack commands
 129 ~~~~~~~~~~~~~~
 130
 131 Stack management
 132 ^^^^^^^^^^^^^^^^
 133
 134 stglink:branch[]::
 135         stgdesc:branch[]
 136 stglink:init[]::
 137         stgdesc:init[]
 138 stglink:clean[]::
 139         stgdesc:clean[]
 140 stglink:pull[]::
 141         stgdesc:pull[]
 142 stglink:rebase[]::
 143         stgdesc:rebase[]
 144
 145 stglink:commit[]::
 146         stgdesc:commit[]
 147 stglink:uncommit[]::
 148         stgdesc:uncommit[]
 149 stglink:assimilate[]::
 150         stgdesc:assimilate[]
 151
 152 Controlling what patches are applied
 153 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 154
 155 stglink:series[]::
 156         stgdesc:series[]
 157 stglink:push[]::
 158         stgdesc:push[]
 159 stglink:pop[]::
 160         stgdesc:pop[]
 161 stglink:goto[]::
 162         stgdesc:goto[]
 163 stglink:float[]::
 164         stgdesc:float[]
 165 stglink:sink[]::
 166         stgdesc:sink[]
 167 stglink:applied[]::
 168         stgdesc:applied[]
 169 stglink:unapplied[]::
 170         stgdesc:unapplied[]
 171 stglink:top[]::
 172         stgdesc:top[]
 173
 174 stglink:hide[]::
 175         stgdesc:hide[]
 176 stglink:unhide[]::
 177         stgdesc:unhide[]
 178
 179 Miscellaneous stack commands
 180 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 181
 182 stglink:patches[]::
 183         stgdesc:patches[]
 184
 185
 186 Patch commands
 187 ~~~~~~~~~~~~~~
 188
 189 Patch management
 190 ^^^^^^^^^^^^^^^^
 191
 192 stglink:new[]::
 193         stgdesc:new[]
 194 stglink:delete[]::
 195         stgdesc:delete[]
 196 stglink:rename[]::
 197         stgdesc:rename[]
 198 stglink:log[]::
 199         stgdesc:log[]
 200
 201 Controlling patch contents
 202 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 203
 204 stglink:files[]::
 205         stgdesc:files[]
 206 stglink:show[]::
 207         stgdesc:show[]
 208 stglink:refresh[]::
 209         stgdesc:refresh[]
 210 stglink:fold[]::
 211         stgdesc:fold[]
 212 stglink:pick[]::
 213         stgdesc:pick[]
 214 stglink:sync[]::
 215         stgdesc:sync[]
 216
 217 Interaction with the rest of the world
 218 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 219
 220 stglink:export[]::
 221         stgdesc:export[]
 222 stglink:import[]::
 223         stgdesc:import[]
 224 stglink:mail[]::
 225         stgdesc:mail[]
 226
 227
 228 Working-copy commands
 229 ~~~~~~~~~~~~~~~~~~~~~
 230
 231 stglink:add[]::
 232         stgdesc:add[]
 233 stglink:rm[]::
 234         stgdesc:rm[]
 235 stglink:cp[]::
 236         stgdesc:cp[]
 237 stglink:status[]::
 238         stgdesc:status[]
 239 stglink:diff[]::
 240         stgdesc:diff[]
 241 stglink:resolved[]::
 242         stgdesc:resolved[]
 243
 244 CONFIGURATION MECHANISM
 245 -----------------------
 246
 247 Starting with 0.12, StGIT uses the same configuration mechanism as
 248 GIT.  See gitlink:git[7] for more details.
 249
 250 TEMPLATES
 251 ---------
 252
 253 A number of StGIT commands make use of template files to provide
 254 useful default texts to be edited by the user.  These '<name>.tmpl'
 255 template files are searched in the following directories:
 256
 257         $GITDIR/
 258         $HOME/.stgit/templates/
 259         /usr/share/stgit/templates/