4 StGit is a command-line application that provides functionality
5 similar to htmllink:http://savannah.nongnu.org/projects/quilt/[Quilt]
6 (i.e. pushing/popping patches to/from a stack), but using Git instead
7 of +diff+ and +patch+. StGit stores its patches in a Git repository as
8 normal Git commits, and provides a number of commands to manipulate
11 This tutorial assumes you are already familiar with the basics of Git
12 (for example, branches, commits, and conflicts). For more information
13 on Git, see manlink:git[1] or htmllink:http://git.or.cz/[the Git home
20 For a full list of StGit commands:
24 For quick help on individual subcommands:
28 For more extensive help on a subcommand:
32 (The documentation is also available in htmllink:stg.html[HTML
39 StGit is not a stand-alone program -- it operates on a Git repository
40 that you have already created, using +git init+ or +git clone+. So get
41 one of those; if you don't have one at hand, try for example
43 $ git clone http://homepage.ntlworld.com/cmarinas/stgit.git
46 Before you can create StGit patches, you have to run stglink:init[]:
50 This initializes the StGit metadata for the current branch. (So if you
51 want to have StGit patches in another branch too, you need to run +stg
52 init+ again in that branch.)
54 NOTE: As a shortcut, stglink:clone[] will run +git clone+ followed by
61 Now we're ready to create our first patch:
63 $ stg new my-first-patch
65 This will create a patch called +my-first-patch+, and open an editor
66 to let you edit the patch's commit message. (If you don't give a name
67 on the command line, StGit will make one up based on the first line of
68 the commit message.) This patch is empty, as stglink:show[] will tell
73 But it won't stay that way for long! Open one of the files in your
74 favorite text editor, change something, and save. You now have some
75 local changes in your tree:
80 Then stgsublink:refresh[] the patch:
84 And voilĂ -- the patch is no longer empty:
87 commit 3de32068c600d40d8af2a9cf1f1c762570ae9610
88 Author: Audrey U. Thor <author@example.com>
89 Date: Sat Oct 4 16:10:54 2008 +0200
91 Tell the world that I've made a patch
93 diff --git a/stgit/main.py b/stgit/main.py
94 index e324179..6398958 100644
97 @@ -171,6 +171,7 @@ def _main():
98 sys.exit(ret or utils.STGIT_SUCCESS)
101 + print 'My first patch!'
106 (I'm assuming you're already familiar with patches like this from Git,
107 but it's really quite simple; in this example, I've added the +$$print
108 'My first patch!'$$+ line to the file +stgit/main.py+, at around line
111 Since the patch is also a regular Git commit, you can also look at it
112 with regular Git tools such as manlink:gitk[].
114 Creating another patch
115 ----------------------
117 We want to make another improvement, so let's create a new patch for
120 $ echo 'Audrey U. Thor' > AUTHORS
121 $ stg new credit --message 'Give me some credit'
124 Note that we can give the commit message on the command line, and that
125 it doesn't matter whether we run stglink:new[] before or after we edit
128 So now we have two patches:
130 $ stg series --description
131 + my-first-patch # This is my first patch
132 > credit # Give me some credit
134 stglink:series[] lists the patches from bottom to top; +$$+$$+ means
135 that a patch is 'applied', and +>+ that it is the 'current', or
138 If we want to make further changes to the topmost patch, we just edit
139 the files and run +stg refresh+. But what if we wanted to change
140 +my-first-patch+? The simplest way is to stgsublink:pop[] the +credit+
141 patch, so that +my-first-patch+ becomes topmost again:
144 Checking for changes in the working directory ... done
145 Popping patch "credit" ... done
146 Now at patch "my-first-patch"
147 $ stg series --description
148 > my-first-patch # This is my first patch
149 - credit # Give me some credit
151 stglink:series[] now shows that +my-first-patch+ is topmost again,
152 which means that stglink:refresh[] will update it with any changes we
155 The minus sign says that +credit+ is 'unapplied' -- this means that
156 it's been temporarily put aside. If you look at the +AUTHORS+ file,
157 you'll see that our change to it is gone; and tools such as
158 manlink:gitk[] will not show it, because it's been edited out of the
159 Git history. But it's just one stglink:push[] command away from being
163 Checking for changes in the working directory ... done
164 Fast-forwarded patch "credit"
165 Now at patch "credit"
167 NOTE: You can omit the patch name argument to stglink:push[] and
168 stglink:pop[]. If you do, you will push the next unapplied patch, and
169 pop the topmost patch, respectively.
171 NOTE: There are at least two more ways to update a non-topmost patch.
172 One is to use stglink:refresh[] with the +$$--patch$$+ flag, the other
173 to create a new patch for the update and then merge it into the other
174 patch with stglink:coalesce[].
177 Keeping commit messages up to date
178 ----------------------------------
180 Since StGit is all about creating readable Git history (or a readable
181 patch series, which is essentially the same thing), one thing you'll
182 want to pay attention to is the commit messages of your patches.
183 stglink:new[] asks you for a commit message when you create a new
184 patch, but as time goes by and you refresh the patch again and again,
185 chances are that the original commit message isn't quite correct
186 anymore. Fortunately, editing the commit message is very easy:
188 $ stg edit <patch-name>
190 In addition to stglink:edit[], you can also give the +$$--edit$$+ flag
191 to stglink:refresh[] -- that way, you get to change the commit message
192 and update the patch at the same time. Use whichever feels most
195 NOTE: stglink:edit[] has a +$$--diff$$+ flag, which gives you the diff
196 text and not just the commit message in your editor. Be aware, though,
197 that if you change the diff so that it no longer applies, the edit
198 will be saved to a file instead of being carried out. If you're not
199 comfortable editing diffs, just treat +$$--diff$$+ as a way to get to
200 'see' the diff while you edit the commit message.
202 If the patch changes considerably, it might even deserve a new name.
203 stglink:rename[] is your friend there.
209 Normally, when you pop a patch, change something, and then later push
210 it again, StGit sorts out everything for you automatically. For
211 example, let's create two patches that modify different files:
213 $ stg clone http://homepage.ntlworld.com/cmarinas/stgit.git stgit
215 $ stg new first --message 'First patch'
216 $ echo '- Do something' >> TODO
218 $ stg new second --message 'Second patch'
219 $ echo '- Install something' >> INSTALL
226 and then push them in the opposite order:
228 $ stg push second first
233 StGit had no problems reordering these patches for us, since they
234 didn't touch the same file. But it would have worked just fine even if
235 they had touched the same file, as long as they didn't change the same
236 part of the file. But what if they did? Let's find out.
239 Checking for changes in the working directory ... done
240 Popping patch "first" ... done
241 Now at patch "second"
242 $ echo '- Do something else' >> TODO
245 Now, both patches add a new line at the end of +TODO+. So what happens
246 when we try to have them both applied?
249 Pushing patch "first" ...
250 CONFLICT (content): Merge conflict in TODO
251 Error: The merge failed during "push".
252 Revert the operation with "stg undo".
253 stg push: 1 conflict(s)
255 StGit is telling us that it couldn't figure out how to push +first+ on
256 top of +second+, now that they both modify +TODO+. We can take a look
257 at the situation with stglink:status[]:
265 As we were told by stglink:push[], the conflict is in the file +TODO+.
266 (If the patch was bigger and touched multiple files, they would all be
267 listed here; prefixed with +C+ if they had conflicts, and +M+ if StGit
268 managed to automatically resolve everything in the file.)
270 NOTE: +TODO.ancestor+, +TODO.current+, and +TODO.patched+ are the
271 three versions of the file that StGit tried to merge. The +.current+
272 file is the version before the patch was applied, +.patched+ is the
273 version in the patch we tried to push, and +.ancestor+ the version
274 that contains neither of the added lines.
276 At this point, we have two options:
278 1. Undo the failed merge with stglink:undo[]. (Remember to use the
279 +$$--hard$$+ flag, since the unresolved conflict means the
280 worktree is not clean.)
282 2. Manually resolve the conflict.
284 To resolve the conflict, open +TODO+ in your favorite editor. It ends
287 ----------------------------------------------------------------------
288 - numeric shortcuts for naming patches near top (eg. +1, -2)
289 - (config?) parameter for number of patches included by "series -s"
295 ----------------------------------------------------------------------
297 The 'conflict markers' +<<<<<<<+, +=======+, and +>>>>>>>+ indicate
298 which lines were already there (+current+) and which were added by the
299 patch (+patched+). Edit the file so that it looks like it should; in
300 this case, we want something like this:
302 ----------------------------------------------------------------------
303 - numeric shortcuts for naming patches near top (eg. +1, -2)
304 - (config?) parameter for number of patches included by "series -s"
307 ----------------------------------------------------------------------
309 Note that ``looks like it should'' includes removing the conflict
312 Now that we've resolved the conflict, we just need to tell StGit about
319 +TODO+ is listed as being modified, not in conflict. And we know from
320 before how to deal with modified files:
324 The conflict is now resolved. We can see that +first+ now looks a
325 little different; it no longer adds a line at the end of the file:
328 commit 8e3ae5f6fa6e9a5f831353524da5e0b91727338e
329 Author: Audrey U. Thor <author@example.com>
330 Date: Sun Oct 5 14:43:42 2008 +0200
334 diff --git a/TODO b/TODO
335 index 812d236..4ef3841 100644
338 @@ -24,4 +24,5 @@ The future, when time allows or if someone else does them:
339 they have scripts for moving the changes in one to the others)
340 - numeric shortcuts for naming patches near top (eg. +1, -2)
341 - (config?) parameter for number of patches included by "series -s"
346 Workflow: Development branch
347 ============================
349 One common use of StGit is to ``polish'' a Git branch before you
350 publish it for others to see. Such history falsification can often be
351 a 'good' thing -- when you (or someone else) needs to look at what you
352 did six months later, you are not really interested in all the false
353 starts and the steps needed to corect them. What you want is the final
354 solution, presented in a way that makes it easy to read and
357 Of course, there are limits. Editing the last few days' worth of
358 history is probably a good idea; editing the last few months' probably
359 isn't. A rule of thumb might be to not mess with history old enough
360 that you don't remember the details anymore. And rewriting history
361 that you have published for others to see (and base their own work on)
362 usually just makes everyone more confused, not less.
364 So, let's take a concrete example. Say that you're hacking on StGit,
365 and have made several Git commits as your work progressed, with commit
366 messages such as ``Improve the snarfle cache'', ``Remove debug
367 printout'', ``New snarfle cache test'', ``Oops, spell function name
368 correctly'', ``Fix documentation error'', and ``More snarfle cache''.
370 Now, this is the actual history, but for obvious reasons, this isn't
371 the kind of history you'd ideally want to find when you six months
372 from now try to figure out exactly where that elusive snarfle cache
373 bug was introduced. So let's turn this into the history we can be
374 proud of. The first step is to make StGit patches out of all those Git
377 $ stg uncommit --number 6
378 Uncommitting 6 patches ...
379 Now at patch "more-snarfle-cache"
381 $ stg series --description
382 + improve-the-snarfle-cache # Improve the snarfle cache
383 + remove-debug-printout # Remove debug printout
384 + new-snarfle-cache-test # New snarfle cache test
385 + oops-spell-function-name-corre # Oops, spell function name correctly
386 + fix-documentation-error # Fix documentation error
387 > more-snarfle-cache # More snarfle cache
389 As you can see, stglink:uncommit[] adds StGit metadata to the last few
390 Git commits, turning them into StGit patches so that we can do stuff
393 NOTE: With the +$$--number$$+ flag, stglink:uncommit[] uncommits that
394 many commits and generates names for them based on their commit
395 messages. If you like, you can instead list the patch names you want
398 At this point, there are a number of things we could do:
400 * Continue developing, and take advantage of e.g. stglink:goto[] or
401 +stg refresh $$--patch$$+ to stick updates in the right patch to
404 * Use e.g. stglink:float[], stglink:sink[], stglink:push[], and
405 stglink:pop[] to reorder patches.
407 * Use stglink:coalesce[] to merge two or more patches into one.
408 stgsublink:coalesce[] pushes and pops so that the patches to be
409 merged are consecutive and unrelated patches aren't in the way,
410 then makes one big patch out of the patches to be merged, and
411 finally pushes the other patches back.
413 Of course, as always when there is pushing involved, there is the
414 possibility of conflicts. If a push results in a conflict, the
415 operation will be halted, and we'll be given the option of either
416 resolving the conflict or undoing.
418 Once we feel that the history is as good as it's going to get, we can
419 remove the StGit metadata, turning the patches back into regular Git
424 TIP: stglink:commit[] can also commit specific patches (named on the
425 command line), leaving the rest alone. This can be used to retire
426 patches as they mature, while keeping the newer and more volatile
430 Workflow: Tracking branch
431 =========================
434 Rebasing a patch series
435 -----------------------
440 Getting patches upstream
441 ------------------------
443 TODO:: export, mail, ...
452 Other stuff that needs to be placed somewhere
453 =============================================
459 TODO:: undo, redo, log, reset
462 Interoperating with Git
463 -----------------------
467 * git commit + repair
469 * git reset HEAD~n + repair
471 * don't do git rebase or git merge, because it won't work
477 TODO:: This section needs revising. I've only fixed the formatting.
478 Most of it should go under "Workflow: Tracking branch"
480 As mentioned in the introduction, StGit stores modifications to your
481 working tree in the form of Git commits. This means if you want to
482 apply your changes to a tree not managed by Git, or send your changes
483 to someone else in e-mail, you need to convert your StGit patches into
484 normal textual diffs that can be applied with the GNU patch command.
485 stglink:diff[] is a powerful way to generate and view textual diffs of
486 patches managed by StGit.
488 To view a diff of the topmost patch:
492 Observe that this does not show any changes in the working directory
493 that have not been saved by a stgsublink:refresh[]. To view just the
494 changes you've made since the last refresh, use:
498 If you want to see the changes made by the patch combined with any
499 unsaved changes in the working directory, try:
501 $ stg diff -r /bottom
503 You can also show the changes to any patch in your stack with:
505 $ stg diff -r <patch>/
507 Use this command to view all the changes in your stack up through the
512 stglink:diff[] supports a number of other features that are very
513 useful. Be sure to take a look at the help information for this
514 command. To convert your StGit patches into patch files:
516 $ stg export [--range=[<patch1>[:<patch2>]]] [<dir-name>]
518 stglink:export[] supports options to automatically number the patches
519 (+-n+) or add the +.diff+ extension (+-d+). If you don't tell
520 stgsublink:export[] where to put the patches, it will create directory
521 named +patch-<branchname>+ in your current directory, and store the
522 patches there. To e-mail a patch or range of patches:
524 $ stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>)
526 stglink:mail[] has a lot of options, so read the output of +stg mail
527 -h+ for more information.
529 You can also import an existing GNU diff patch file as a new StGit
530 patch with a single command. stglink:import[] will automatically parse
531 through the patch file and extract a patch description. Use:
533 $ stg import [<file>]
535 This is the equivalent of
541 Sometimes the patch file won't apply cleanly. In that case,
542 stglink:import[] will leave you with an empty StGit patch, to which
543 you then apply the patch file by hand using "patch -i" and your
546 To merge a GNU diff file (defaulting to the standard input) into the
551 This command supports a +$$--threeway$$+ option which applies the
552 patch onto the bottom of the topmost one and performs a three-way
559 TODO:: This section needs revising. I've only fixed the formatting.
561 stglink:export[] and stglink:mail[] use templates for generating the
562 patch files or e-mails. The default templates are installed under
563 +<prefix>/share/stgit/templates/+ and, combined with the extra options
564 available for these commands, should be enough for most users. The
565 template format uses the standard Python string formatting rules. The
566 variables available are listed in the the manual pages for each
567 command. stglink:mail[] can also send an initial 'cover' e-mail for
568 which there is no default template. The
569 +<prefix>/share/stgit/examples/firstmail.tmpl+ file can be used as an
570 example. A default description for new patches can be defined in the
571 +.git/ patchdescr.tmpl+ file. This is useful for things like