| 1 | StGIT Tutorial |
| 2 | ############## |
| 3 | |
| 4 | |
| 5 | StGIT is a Python application that provides functionality similar to |
| 6 | quilt (i.e. pushing/popping patches to/from a stack) using GIT instead |
| 7 | of 'diff' and 'patch'. StGIT stores its patches in a GIT repository as |
| 8 | normal GIT commit objects. |
| 9 | StGIT is not an SCM interface on top of GIT. For standard SCM |
| 10 | operations, either use GIT's porcelain commands or the Cogito tool. |
| 11 | StGIT is available for download at http://www.procode.org/stgit/ . |
| 12 | This tutorial assumes you are already familiar with GIT. For more |
| 13 | information on GIT, see the GIT_tutorial or git(7) . |
| 14 | |
| 15 | |
| 16 | Basic Operation |
| 17 | =============== |
| 18 | |
| 19 | Help |
| 20 | ---- |
| 21 | |
| 22 | For a full list of StGIT commands: |
| 23 | |
| 24 | stg help |
| 25 | |
| 26 | For help on individual subcommands: |
| 27 | |
| 28 | stg <cmd> (-h | --help) |
| 29 | |
| 30 | |
| 31 | Repository initialisation |
| 32 | ------------------------- |
| 33 | |
| 34 | In stand-alone mode, StGIT is used in conjunction with a GIT repository |
| 35 | that is already initialised (using 'git-init-db'). StGIT cannot be used |
| 36 | outside of a GIT repository. |
| 37 | Any branch in a GIT repository may be managed by StGIT. Each branch |
| 38 | managed by StGIT contains an independent series of StGIT patches. |
| 39 | To initialise an existing GIT branch to be managed by StGIT, cd into the |
| 40 | top of your GIT repository, check out the branch you'd like to manage |
| 41 | with StGIT, and type: |
| 42 | |
| 43 | stg init |
| 44 | |
| 45 | Run the 'stg init' command for any pre-existing GIT branches intended to |
| 46 | be used with StGIT. |
| 47 | You can switch between GIT branches with: |
| 48 | |
| 49 | stg branch [<branch name>] |
| 50 | |
| 51 | This checks out the named branch and places you at the topmost applied |
| 52 | StGIT patch in that branch. |
| 53 | Alternately, you can create branches using only StGIT commands, which |
| 54 | will automatically prepare them for use with StGIT: |
| 55 | |
| 56 | stg branch --create <new branch> |
| 57 | |
| 58 | |
| 59 | Working with remote repositories |
| 60 | -------------------------------- |
| 61 | |
| 62 | With a single command, StGIT can create and initialize a GIT repository |
| 63 | which mirrors a remote GIT repository. This is known as cloning. All GIT |
| 64 | transports are supported. |
| 65 | To clone a repository, use: |
| 66 | |
| 67 | stg clone <repository> <local-dir> |
| 68 | |
| 69 | This creates a fresh local repository, initialises a GIT database in it, |
| 70 | pulls the latest version of the remote, and creates and initialises a |
| 71 | 'master' branch for use with StGIT. |
| 72 | At any time you can pull the latest changes from the remote repository. |
| 73 | By default, StGIT pulls from the location stored in .git/branches/ |
| 74 | origin, and updates the base of the current branch. |
| 75 | To pull the latest changes from a remote repository, use: |
| 76 | |
| 77 | stg pull [<branch> or 'origin'] |
| 78 | |
| 79 | This command removes all applied StGIT patches from the current branch, |
| 80 | updates the branch's base commit, then attempts to re-apply the patches. |
| 81 | Any merge conflicts will halt this process, allowing you to clean up the |
| 82 | conflicts and continue (see below). |
| 83 | If the maintainer of the remote repository includes one of your patches |
| 84 | in the published repository that you pull from, StGIT can usually |
| 85 | recognize that an incoming patch from the remote matches one of yours, |
| 86 | and it turns your local version into an empty patch. |
| 87 | To automatically delete empty patches after a pull, use: |
| 88 | |
| 89 | stg clean |
| 90 | |
| 91 | As a convention, you should avoid working in the 'master' branch and use |
| 92 | it only as a reference, since it reflects someone else's work. If you |
| 93 | decide to publish your GIT repository, you'll want your own work |
| 94 | separated into its own branch to make it convenient for others to pull |
| 95 | just your patches. |
| 96 | |
| 97 | Getting started: creating a patch |
| 98 | --------------------------------- |
| 99 | |
| 100 | Changes to your working directory are saved in a patch. An StGIT patch |
| 101 | is simply a saved set of modifications to your working directory, plus a |
| 102 | saved description. To create an empty StGIT patch in the current branch: |
| 103 | |
| 104 | stg new <name> |
| 105 | |
| 106 | To save the changes you've made (that is, to refresh a patch), use: |
| 107 | |
| 108 | stg refresh |
| 109 | |
| 110 | To discard changes in your working directory, use: |
| 111 | |
| 112 | git checkout -f |
| 113 | |
| 114 | This restores your working directory to the state it was in the last |
| 115 | time the patch was refreshed. |
| 116 | Modified files that haven't been saved via a refresh operation can be |
| 117 | viewed with: |
| 118 | |
| 119 | stg status |
| 120 | |
| 121 | You can view modified files that have already been saved into a patch: |
| 122 | |
| 123 | stg files |
| 124 | |
| 125 | The 'stg refresh' command automatically notes changes to files that |
| 126 | already exist in the working directory, but you have to tell StGIT |
| 127 | explicitly if you add, remove, or rename files. |
| 128 | To record the addition or deletion of files in your new patch: |
| 129 | |
| 130 | stg add [<file>*] |
| 131 | stg rm [<file>*] |
| 132 | |
| 133 | To record the renaming of a file in your new patch, issue both of these |
| 134 | commands: |
| 135 | |
| 136 | stg rm <oldfilename> |
| 137 | stg add <newfilename> |
| 138 | |
| 139 | |
| 140 | Stack manipulation: managing multiple patches |
| 141 | --------------------------------------------- |
| 142 | |
| 143 | StGIT can manage more than one patch at a time. A series of StGIT |
| 144 | patches in a GIT branch are known collectively as a stack. The new patch |
| 145 | you created above is now the topmost patch in your stack. You can always |
| 146 | see the name of the topmost (current) patch with: |
| 147 | |
| 148 | stg top |
| 149 | |
| 150 | The topmost patch is used as the default patch for most StGIT |
| 151 | operations. It is the default target of the 'stg refresh' command, for |
| 152 | example. |
| 153 | Patches that are pushed onto the stack are referred to as applied, and |
| 154 | patches that are popped off the stack are referred to as unapplied. |
| 155 | To push/pop a patch to/from a stack: |
| 156 | |
| 157 | stg push [--all | <name>] |
| 158 | stg pop [--all] |
| 159 | |
| 160 | The last patch you pushed is the topmost patch. This patch is always in |
| 161 | the applied list; StGIT can't operate on an unapplied patch unless you |
| 162 | apply it first. |
| 163 | You can display the order of patches in a stack with one of these |
| 164 | commands: |
| 165 | |
| 166 | stg series |
| 167 | stg applied |
| 168 | stg unapplied |
| 169 | |
| 170 | By default the 'stg push' command applies the first patch in the |
| 171 | unapplied list, but you can push any patch in the unapplied list by |
| 172 | giving the name of the patch. This is useful if you want to reorder the |
| 173 | patches in a stack. |
| 174 | During a push operation, merge conflicts can occur (especially if you |
| 175 | are changing the order of the patches in your stack). If the push causes |
| 176 | merge conflicts, they need to be fixed and 'stg resolved' run (see |
| 177 | below). A 'push' operation can also be reverted with 'stg push --undo'. |
| 178 | A few more stack basics; to rename a patch: |
| 179 | |
| 180 | stg rename <old-name> <new-name> |
| 181 | |
| 182 | To delete a patch: |
| 183 | |
| 184 | stg delete <name> |
| 185 | |
| 186 | This permanently discards the named patch. In other words, the patch no |
| 187 | longer appears in either the applied or unapplied lists, and cannot be |
| 188 | reapplied to the series. |
| 189 | You may want to make patches in your stack a permanent part of your GIT |
| 190 | repository, for example if you are publishing your repository to others. |
| 191 | To do this, use: |
| 192 | |
| 193 | stg commit |
| 194 | |
| 195 | This merges all applied patches in your patch series into the GIT |
| 196 | repository and removes them from your stack. Use this command only if |
| 197 | you want to permanently store the applied patches and no longer manage |
| 198 | them with StGIT. |
| 199 | |
| 200 | Converting between StGIT patches and text diffs |
| 201 | ----------------------------------------------- |
| 202 | |
| 203 | As mentioned in the introduction, StGIT stores modifications to your |
| 204 | working tree in the form of GIT commits. This means if you want to apply |
| 205 | your changes to a tree not managed by GIT, or send your changes to |
| 206 | someone else in e-mail, you need to convert your StGIT patches into |
| 207 | normal textual diffs that can be applied with the GNU 'patch' command. |
| 208 | The 'stg diff' command is a powerful way to generate and view textual |
| 209 | diffs of patches managed by StGIT. |
| 210 | To view a diff of the topmost patch: |
| 211 | |
| 212 | stg diff -r / |
| 213 | |
| 214 | Observe that this does not show any changes in the working directory |
| 215 | that have not been saved by a 'refresh'. To view just the changes you've |
| 216 | made since the last refresh, use: |
| 217 | |
| 218 | stg diff -r /top |
| 219 | |
| 220 | If you want to see the changes made by the patch combined with any |
| 221 | unsaved changes in the working directory, try: |
| 222 | |
| 223 | stg diff -r /bottom |
| 224 | |
| 225 | You can also show the changes to any patch in your stack with: |
| 226 | |
| 227 | stg diff -r <patch>/ |
| 228 | |
| 229 | Use this command to view all the changes in your stack up through the |
| 230 | current patch: |
| 231 | |
| 232 | stg diff -r base |
| 233 | |
| 234 | The 'stg diff' command supports a number of other features that are very |
| 235 | useful. Be sure to take a look at the help information for this command. |
| 236 | To convert your StGIT patches into patch files: |
| 237 | |
| 238 | stg export [--range=[<patch1>[:<patch2>]]] [<dir-name>] |
| 239 | |
| 240 | The 'export' command supports options to automatically number the |
| 241 | patches (-n) or add the '.diff' extension (-d). If you don't tell "stg |
| 242 | export" where to put the patches, it will create directory named "patch- |
| 243 | branchname" in your current directory, and store the patches there. |
| 244 | To e-mail a patch or range of patches: |
| 245 | |
| 246 | stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>) |
| 247 | |
| 248 | "stg mail" has a lot of options, so read the output of "stg mail -h" for |
| 249 | more information. |
| 250 | You can also import an existing GNU diff patch file as a new StGIT patch |
| 251 | with a single command. "stg import" will automatically parse through the |
| 252 | patch file and extract a patch description. Use: |
| 253 | |
| 254 | stg import [<file>] |
| 255 | |
| 256 | This is the equivalent of "stg new" followed by "patch -i <file>", then |
| 257 | "stg refresh -e". |
| 258 | Sometimes the patch file won't apply cleanly. In that case, "stg import" |
| 259 | will leave you with an empty StGIT patch, to which you then apply the |
| 260 | patch file by hand using "patch -i" and your favorite editor. |
| 261 | To merge a GNU diff file (defaulting to the standard input) into the |
| 262 | topmost patch: |
| 263 | |
| 264 | stg fold [<file>] |
| 265 | |
| 266 | This command supports a '--threeway' option which applies the patch onto |
| 267 | the bottom of the topmost one and performs a three-way merge. |
| 268 | |
| 269 | |
| 270 | Advanced Usage |
| 271 | ============== |
| 272 | |
| 273 | Handling merge conflicts |
| 274 | ------------------------ |
| 275 | |
| 276 | Pushing a patch on the stack can fail if the patch cannot be applied |
| 277 | cleanly. This usually happens if there are overlapping changes in the |
| 278 | tree, the patch depends on another patch which is not applied, or if a |
| 279 | patch was not merged upstream in the exact form it was sent. |
| 280 | The 'push' operation stops after the first patch with conflicts. The |
| 281 | 'status' command shows the conflict files by marking them with a 'C'. If |
| 282 | the 'keeporig' options is set to 'yes' (the default), the original files |
| 283 | involved in the merge operations are left in the tree as <file>.older, |
| 284 | <file>.local and <file>.remote for better analysis of the conflict. If |
| 285 | 'diff3' is used as the merger (the default), markers are added to the |
| 286 | conflicted files as well. |
| 287 | Run the 'resolved' command to mark the conflicts resolved and remove the |
| 288 | temporary merge files from the working tree. Then run the 'refresh' |
| 289 | command to update the StGIT patch with the modifications you made to |
| 290 | resolve the conflict. |
| 291 | |
| 292 | |
| 293 | Configuration file |
| 294 | ------------------ |
| 295 | |
| 296 | StGIT tries to read the configuration options from the following files: |
| 297 | /etc/stgitrc, ~/.stgitrc and .git/stgitrc. The latter overrides the |
| 298 | options in the former files. If no file is found, the defaults are used. |
| 299 | An example configuration file with options description can be found in |
| 300 | the examples/ directory. Most users would probably only define the |
| 301 | 'smtpserver' option used by the 'mail' command. |
| 302 | The gitmergeonefile.py script does the three-way merging on individual |
| 303 | files using the tool specified by the 'merger' option. The user can |
| 304 | specify a smarter tool to be used. |
| 305 | |
| 306 | |
| 307 | Templates |
| 308 | --------- |
| 309 | |
| 310 | The 'export' and 'mail' commands use templates for generating the patch |
| 311 | files or e-mails. The default templates are installed under <prefix>/ |
| 312 | share/stgit/templates/ and, combined with the extra options available |
| 313 | for the commands, should be enough for most users. The template format |
| 314 | uses the standard Python string formatting rules. The variables |
| 315 | available are shown in the the help message for the commands. |
| 316 | The 'mail' command can also send an initial e-mail for which there is no |
| 317 | default template. The <prefix>/share/stgit/examples/firstmail.tmpl file |
| 318 | can be used as an example. |
| 319 | A default description for new patches can be defined in the .git/ |
| 320 | patchdescr.tmpl file. This is useful for things like signed-off-by |
| 321 | lines. |
| 322 | |
| 323 | |
| 324 | Merging two patches into one |
| 325 | ---------------------------- |
| 326 | |
| 327 | There is no command to do this directly at the moment but one can export |
| 328 | the patch to be merged and use the 'stg fold' command on the generated |
| 329 | diff file. Assuming that the merged patch was not already applied, the |
| 330 | operation will succeed. Pushing the merged patch onto the stack will |
| 331 | result in an empty patch (StGIT notifying the user) that can be safely |
| 332 | deleted. |
| 333 | |
| 334 | |
| 335 | Technical Information |
| 336 | ===================== |
| 337 | |
| 338 | A bit of StGIT patch theory |
| 339 | --------------------------- |
| 340 | |
| 341 | We assume that a patch is a diff between two nodes - bottom and top. A |
| 342 | node is a commit SHA1 id or tree SHA1 id in the GIT terminology: |
| 343 | |
| 344 | P - patch |
| 345 | N - node |
| 346 | |
| 347 | P = diff(Nt, Nb) |
| 348 | |
| 349 | Nb - bottom (start) node |
| 350 | Nt - top (end) node |
| 351 | Nf - first node (for log generation) |
| 352 | |
| 353 | For an ordered stack of patches: |
| 354 | |
| 355 | P1 = diff(N1, N0) |
| 356 | P2 = diff(N2, N1) |
| 357 | ... |
| 358 | |
| 359 | |
| 360 | Ps = P1 + P2 + P3 + ... = diff(Nst, Nsb) |
| 361 | |
| 362 | Ps - the big patch of the whole stack |
| 363 | Nsb - bottom stack node (= N0) |
| 364 | Nst - top stack node (= Nn) |
| 365 | |
| 366 | Applying (pushing) a patch on the stack (Nst can differ from Nb) is done |
| 367 | by diff3 merging. The new patch becomes: |
| 368 | |
| 369 | P' = diff(Nt', Nb') |
| 370 | Nb' = Nst |
| 371 | Nt' = diff3(Nst, Nb, Nt) |
| 372 | |
| 373 | (note that the diff3 parameters order is: branch1, ancestor, branch2) |
| 374 | The above operation allows easy patch re-ordering. |
| 375 | Removing (popping) a patch from the stack is done by simply setting the |
| 376 | Nst to Nb. |
| 377 | |
| 378 | |
| 379 | Layout of the .git directory |
| 380 | ---------------------------- |
| 381 | |
| 382 | HEAD -> refs/heads/<something> |
| 383 | objects/ |
| 384 | ??/ |
| 385 | ... |
| 386 | refs/ |
| 387 | heads/ |
| 388 | master - the master commit id |
| 389 | ... |
| 390 | tags/ |
| 391 | ... |
| 392 | branches/ |
| 393 | ... |
| 394 | patches/ |
| 395 | master/ |
| 396 | applied - list of applied patches |
| 397 | unapplied - list of not-yet applied patches |
| 398 | current - name of the topmost patch |
| 399 | patch1/ |
| 400 | bottom - the bottom id of the patch |
| 401 | top - the top id of the patch |
| 402 | description - the patch description |
| 403 | authname - author's name |
| 404 | authemail - author's e-mail |
| 405 | commname - committer's name |
| 406 | commemail - committer's e-mail |
| 407 | patch2/ |
| 408 | ... |
| 409 | ... |
| 410 | ... |