Documentation/stg.txt

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