Documentation/stg.txt

   1 stg(1)
   2 ======
   3 Yann Dirson <ydirson@altern.org>
   4 v0.13, 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 Patch logs
  80 ~~~~~~~~~~
  81
  82 The successive versions of each patch are stored in a "patch log".
  83
  84 TODO: document patchlog, explain empty refreshs, non-empty pushs,
  85 conflicts, partial pushs, ...
  86
  87
  88 OPTIONS
  89 -------
  90
  91 The following generic option flags are available.  Additional options
  92 are available per-command, and documented in the command-specific
  93 documentation.
  94
  95 --version::
  96         Prints the StGIT suite version that the 'stg' program came
  97         from, as well as version of other components used, such as GIT
  98         and Python.
  99
 100 --help::
 101         Prints the synopsis and a list of all commands.  If a git
 102         command is given this option will display the specific help
 103         for that command.
 104
 105 STGIT COMMANDS
 106 --------------
 107
 108 We divide StGIT commands in thematic groups, according to the primary
 109 type of object they create or change.
 110
 111 ifdef::backend-docbook[]
 112 Here is a short description of each command. A more detailed
 113 description is available in individual command manpages.  Those
 114 manpages are named 'stg-<command>(1)'.
 115 endif::backend-docbook[]
 116
 117 Generic commands
 118 ~~~~~~~~~~~~~~~~
 119
 120 User-support commands not touching the repository.
 121
 122 stg help::
 123         stgdesc:help[]
 124 stg version::
 125         stgdesc:version[]
 126 stg copyright::
 127         stgdesc:copyright[]
 128
 129 Repository commands
 130 ~~~~~~~~~~~~~~~~~~~
 131
 132 stglink:clone[]::
 133         stgdesc:clone[]
 134 stglink:id[]::
 135         stgdesc:id[]
 136
 137 Stack commands
 138 ~~~~~~~~~~~~~~
 139
 140 Stack management
 141 ^^^^^^^^^^^^^^^^
 142
 143 stglink:branch[]::
 144         stgdesc:branch[]
 145 stglink:init[]::
 146         stgdesc:init[]
 147 stglink:clean[]::
 148         stgdesc:clean[]
 149 stglink:pull[]::
 150         stgdesc:pull[]
 151 stglink:rebase[]::
 152         stgdesc:rebase[]
 153
 154 stglink:commit[]::
 155         stgdesc:commit[]
 156 stglink:uncommit[]::
 157         stgdesc:uncommit[]
 158 stglink:assimilate[]::
 159         stgdesc:assimilate[]
 160
 161 Controlling what patches are applied
 162 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 163
 164 stglink:series[]::
 165         stgdesc:series[]
 166 stglink:push[]::
 167         stgdesc:push[]
 168 stglink:pop[]::
 169         stgdesc:pop[]
 170 stglink:goto[]::
 171         stgdesc:goto[]
 172 stglink:float[]::
 173         stgdesc:float[]
 174 stglink:sink[]::
 175         stgdesc:sink[]
 176 stglink:applied[]::
 177         stgdesc:applied[]
 178 stglink:unapplied[]::
 179         stgdesc:unapplied[]
 180 stglink:top[]::
 181         stgdesc:top[]
 182
 183 stglink:hide[]::
 184         stgdesc:hide[]
 185 stglink:unhide[]::
 186         stgdesc:unhide[]
 187
 188 Miscellaneous stack commands
 189 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 190
 191 stglink:patches[]::
 192         stgdesc:patches[]
 193
 194
 195 Patch commands
 196 ~~~~~~~~~~~~~~
 197
 198 Patch management
 199 ^^^^^^^^^^^^^^^^
 200
 201 stglink:new[]::
 202         stgdesc:new[]
 203 stglink:delete[]::
 204         stgdesc:delete[]
 205 stglink:rename[]::
 206         stgdesc:rename[]
 207 stglink:log[]::
 208         stgdesc:log[]
 209
 210 Controlling patch contents
 211 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 212
 213 stglink:files[]::
 214         stgdesc:files[]
 215 stglink:show[]::
 216         stgdesc:show[]
 217 stglink:refresh[]::
 218         stgdesc:refresh[]
 219 stglink:fold[]::
 220         stgdesc:fold[]
 221 stglink:pick[]::
 222         stgdesc:pick[]
 223 stglink:sync[]::
 224         stgdesc:sync[]
 225
 226 Interaction with the rest of the world
 227 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 228
 229 stglink:export[]::
 230         stgdesc:export[]
 231 stglink:import[]::
 232         stgdesc:import[]
 233 stglink:mail[]::
 234         stgdesc:mail[]
 235
 236
 237 Working-copy commands
 238 ~~~~~~~~~~~~~~~~~~~~~
 239
 240 stglink:add[]::
 241         stgdesc:add[]
 242 stglink:rm[]::
 243         stgdesc:rm[]
 244 stglink:cp[]::
 245         stgdesc:cp[]
 246 stglink:status[]::
 247         stgdesc:status[]
 248 stglink:diff[]::
 249         stgdesc:diff[]
 250 stglink:resolved[]::
 251         stgdesc:resolved[]
 252
 253 CONFIGURATION MECHANISM
 254 -----------------------
 255
 256 Starting with 0.12, StGIT uses the same configuration mechanism as
 257 GIT.  See gitlink:git[7] for more details.
 258
 259 TEMPLATES
 260 ---------
 261
 262 A number of StGIT commands make use of template files to provide
 263 useful default texts to be edited by the user.  These '<name>.tmpl'
 264 template files are searched in the following directories:
 265
 266         $GITDIR/
 267         $HOME/.stgit/templates/
 268         /usr/share/stgit/templates/