chiark - git - mdw - stgit/blob - README

   1 Stacked GIT
   2 ===========
   3
   4 StGIT is a Python application providing similar functionality to Quilt
   5 (i.e. pushing/popping patches to/from a stack) on top of GIT. These
   6 operations are performed using GIT commands and the patches are stored
   7 as GIT commit objects, allowing easy merging of the StGIT patches into
   8 other repositories using standard GIT functionality.
   9
  10 Note that StGIT is not an SCM interface on top of GIT and it expects a
  11 previously initialised GIT repository (unless it is cloned using StGIT
  12 directly). For standard SCM operations, either use plain GIT commands
  13 or the Cogito tool but it is not recommended to mix them with the
  14 StGIT commands.
  15
  16 For the latest version see http://www.procode.org/stgit/
  17
  18
  19 Basic Operations
  20 ================
  21
  22 See the help on individual commands for the full set of options.
  23
  24 Help
  25 ----
  26
  27 For a full list of commands:
  28
  29         stg help
  30
  31 For help on individual commands:
  32
  33         stg <cmd> (-h | --help)
  34
  35 Repository initialisation/updating
  36 ----------------------------------
  37
  38 To clone a repository (all the GIT repository types are accepted):
  39
  40         stg clone <repository> <local-dir>
  41
  42 To initialise an existing GIT repository to be used with StGIT (not
  43 needed if the cloning was done using StGIT):
  44
  45         stg init
  46
  47 For people switching between multiple branches in the same repository,
  48 the 'init' command needs to be run for all the branches intended to be
  49 used with StGIT.
  50
  51 To pull the latest changes from the remote repository (defaulting to
  52 the value in .git/branches/origin):
  53
  54         stg pull [<branch> or 'origin']
  55
  56 The 'pull' command takes care of updating all the patches in the stack
  57 so that they apply cleanly (the user is notified of the possible
  58 conflicts).
  59
  60 Stack manipulation
  61 ------------------
  62
  63 To create/delete a patch:
  64
  65         stg new <name>
  66         stg delete <name>
  67
  68 The 'new' command also sets the topmost patch to the newly created
  69 one.
  70
  71 To automatically delete the empty patches:
  72
  73         stg clean
  74
  75 To push/pop a patch to/from the stack:
  76
  77         stg push [--all | <name or first unapplied>]
  78         stg pop [--all | <name or topmost>]
  79
  80 Note that the 'push' command can apply any patch in the unapplied
  81 list. This is useful if one wants to reorder the patches. If there are
  82 conflicts, they need to be fixed and 'stg resolved' run. The 'push'
  83 operation can also be reverted with 'stg push --undo'.
  84
  85 To rename a patch:
  86
  87         stg rename <old-name> <new-name>
  88
  89 To import an existing GNU diff patch file (defaulting to the standard
  90 input):
  91
  92         stg import [<file>]
  93
  94 To inspect the stack status:
  95
  96         stg series
  97         stg applied
  98         stg unapplied
  99         stg top
 100
 101 To export a patch series (or a range of patches):
 102
 103         stg export [--range=[<patch1>[:<patch2>]]] [<dir-name or 'patches'>]
 104
 105 The 'export' command supports options to automatically number the
 106 patches (-n) or add the '.diff' extension (-d).
 107
 108 To e-mail a patch or range of patches:
 109
 110         stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>)
 111
 112 Changes to the topmost patch
 113 ----------------------------
 114
 115 Any modified file already under revision control will automatically be
 116 included in the topmost patch.
 117
 118 To add/delete files to/from the topmost patch:
 119
 120         stg add [<file>*]
 121         stg rm [<file>*]
 122
 123 To inspect the tree status:
 124
 125         stg status
 126
 127 To get a diff between 2 revisions:
 128
 129         stg diff [-r rev1[:[rev2]]]
 130
 131 A revision name can be of the form '([patch]/[bottom | top]) | base |
 132 <tree-ish>' If the patch name is not specified but '/' is passed, the
 133 topmost patch is used. If neither 'bottom' nor 'top' follows the '/',
 134 the whole patch diff is displayed (this does not include the local
 135 changes).
 136
 137 Note than when the first patch is pushed on the stack, the current
 138 HEAD is saved in the .git/refs/heads/base file for easy reference to
 139 the base of the stack.
 140
 141 To save the tree changes to the current patch and the GIT repository:
 142
 143         stg refresh
 144
 145 The 'refresh' command also allows the modification of the patch
 146 description and the author/maintainer information.
 147
 148 To display the files modified by a patch (defaulting to the topmost
 149 one):
 150
 151         stg files [<patch>]
 152
 153 To merge a GNU diff file (defaulting to the standard input) into the
 154 topmost patch:
 155
 156         stg fold [<file>]
 157
 158 This command supports a '--threeway' option which applies the patch
 159 onto the bottom of the topmost one and performs a three-way merge.
 160
 161
 162 Advanced Usage
 163 ==============
 164
 165 Configuration file
 166 ------------------
 167
 168 StGIT tries to read the configuration options from the following
 169 files: /etc/stgitrc, ~/.stgitrc and .git/stgitrc. The latter overrides
 170 the options in the former files. If no file is found, the defaults are
 171 used.
 172
 173 An example configuration file with options description can be found in
 174 the examples/ directory. Most users would probably only define the
 175 'smtpserver' option used by the 'mail' command.
 176
 177 The gitmergeonefile.py script does the three-way merging on individual
 178 files using the tool specified by the 'merger' option. The user can
 179 specify a smarter tool to be used.
 180
 181 Templates
 182 ---------
 183
 184 The 'export' and 'mail' commands use templates for generating the
 185 patch files or e-mails. The default templates are installed under
 186 <prefix>/share/stgit/templates/ and, combined with the extra options
 187 available for the commands, should be enough for most users. The
 188 template format uses the standard Python string formatting rules. The
 189 variables available are shown in the the help message for the
 190 commands.
 191
 192 The 'mail' command can also send an initial e-mail for which there is
 193 no default template. The <prefix>/share/stgit/examples/firstmail.tmpl
 194 file can be used as an example.
 195
 196 A default description for new patches can be defined in the
 197 .git/patchdescr.tmpl file. This is useful for things like
 198 signed-off-by lines.
 199
 200 Dealing with conflicts
 201 ----------------------
 202
 203 Pushing a patch on the stack can fail if the patch cannot be applied
 204 cleanly. This usually happens if there are overlapping changes in the
 205 tree, the patch depends on other patch which is not applied or if a
 206 patch was not merged upstream in the exact form it was sent.
 207
 208 The 'push' operation will stop after the first patch with
 209 conflicts. The 'status' command shows the conflict files by marking
 210 them with a 'C'. If the 'keeporig' options is set to 'yes' (the
 211 default), the original files involved in the merge operations are left
 212 in the tree as <file>.older, <file>.local and <file>.remote for a
 213 better analysis by the user. If 'diff3' is used as the merger (the
 214 default), conflict markers can be found in the corresponding files as
 215 well.
 216
 217 Once the conflict is fixed, the 'resolved' command has to be run to
 218 clear the conflict state. This command also removes the original files
 219 involved in the merge for a given file.
 220
 221 Merging two patches into one
 222 ----------------------------
 223
 224 There is no command to do this directly at the moment but one can
 225 export the patch to be merged and use the 'stg fold' command on the
 226 generated diff file. Assuming that the merged patch was not already
 227 applied, the operation will succeed. Pushing the merged patch onto the
 228 stack will result in an empty patch (StGIT notifying the user) that
 229 can be safely deleted.
 230
 231
 232 .git/ Directory Structure
 233 =========================
 234
 235 HEAD                    -> refs/heads/<something>
 236 objects/
 237   ??/
 238   ...
 239 refs/
 240   heads/
 241     master              - the master commit id
 242     ...
 243   bases/
 244     master              - the bottom id of the stack (to get a big diff)
 245     ...
 246   tags/
 247     ...
 248   branches/
 249     ...
 250   patches/
 251     master/
 252       applied           - list of applied patches
 253       unapplied         - list of not-yet applied patches
 254       current           - name of the topmost patch
 255       patch1/
 256         bottom          - the bottom id of the patch
 257         top             - the top id of the patch
 258         description     - the patch description
 259         authname        - author's name
 260         authemail       - author's e-mail
 261         commname        - committer's name
 262         commemail       - committer's e-mail
 263       patch2/
 264         ...
 265       ...
 266     ...
 267
 268
 269 A Bit of StGIT Patch Theory
 270 ===========================
 271
 272 We assume that a patch is a diff between two nodes - bottom and top. A
 273 node is a commit SHA1 id or tree SHA1 id in the GIT terminology:
 274
 275 P - patch
 276 N - node
 277
 278 P = diff(Nt, Nb)
 279
 280         Nb - bottom (start) node
 281         Nt - top (end) node
 282         Nf - first node (for log generation)
 283
 284 For an ordered stack of patches:
 285
 286 P1 = diff(N1, N0)
 287 P2 = diff(N2, N1)
 288 ...
 289
 290 Ps = P1 + P2 + P3 + ... = diff(Nst, Nsb)
 291
 292         Ps  - the big patch of the whole stack
 293         Nsb - bottom stack node (= N0)
 294         Nst - top stack node (= Nn)
 295
 296 Applying (pushing) a patch on the stack (Nst can differ from Nb) is
 297 done by diff3 merging. The new patch becomes:
 298
 299 P' = diff(Nt', Nb')
 300 Nb' = Nst
 301 Nt' = diff3(Nst, Nb, Nt)
 302
 303 (note that the diff3 parameters order is: branch1, ancestor, branch2)
 304
 305 The above operation allows easy patch re-ordering.
 306
 307 Removing (popping) a patch from the stack is done by simply setting
 308 the Nst to Nb.