4 StGit is a command-line application that provides functionality
5 similar to link: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 linkman:git[1] or link: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 link: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 git://repo.or.cz/stgit.git
46 Before you can create StGit patches, you have to run linkstg: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, linkstg: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 linkstg: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 linkstgsub: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
107 link:http://en.wikipedia.org/wiki/Diff#Unified_format[unified
108 diff] patches like this from Git, but it's really quite simple; in
109 this example, I've added the +$$print 'My first patch!'$$+ line to the
110 file +stgit/main.py+, at around line 171.)
112 Since the patch is also a regular Git commit, you can also look at it
113 with regular Git tools such as linkman:gitk[].
115 Creating another patch
116 ----------------------
118 We want to make another improvement, so let's create a new patch for
121 $ echo 'Audrey U. Thor' > AUTHORS
122 $ stg new credit --message 'Give me some credit'
125 Note that we can give the commit message on the command line, and that
126 it doesn't matter whether we run linkstg:new[] before or after we edit
129 So now we have two patches:
131 $ stg series --description
132 + my-first-patch # This is my first patch
133 > credit # Give me some credit
135 linkstg:series[] lists the patches from bottom to top; +$$+$$+ means
136 that a patch is 'applied', and +>+ that it is the 'current', or
139 If we want to make further changes to the topmost patch, we just edit
140 the files and run +stg refresh+. But what if we wanted to change
141 +my-first-patch+? The simplest way is to linkstgsub:pop[] the +credit+
142 patch, so that +my-first-patch+ becomes topmost again:
145 Checking for changes in the working directory ... done
146 Popping patch "credit" ... done
147 Now at patch "my-first-patch"
148 $ stg series --description
149 > my-first-patch # This is my first patch
150 - credit # Give me some credit
152 linkstg:series[] now shows that +my-first-patch+ is topmost again,
153 which means that linkstg:refresh[] will update it with any changes we
156 The minus sign says that +credit+ is 'unapplied' -- this means that
157 it's been temporarily put aside. If you look at the +AUTHORS+ file,
158 you'll see that our change to it is gone; and tools such as
159 linkman:gitk[] will not show it, because it's been edited out of the
160 Git history. But it's just one linkstg:push[] command away from being
164 Checking for changes in the working directory ... done
165 Fast-forwarded patch "credit"
166 Now at patch "credit"
168 NOTE: You can omit the patch name argument to linkstg:push[] and
169 linkstg:pop[]. If you do, you will push the next unapplied patch, and
170 pop the topmost patch, respectively.
172 NOTE: There are at least two more ways to update a non-topmost patch.
173 One is to use linkstg:refresh[] with the +$$--patch$$+ flag, the other
174 to create a new patch for the update and then merge it into the other
175 patch with linkstg:squash[].
178 Keeping commit messages up to date
179 ----------------------------------
181 Since StGit is all about creating readable Git history (or a readable
182 patch series, which is essentially the same thing), one thing you'll
183 want to pay attention to is the commit messages of your patches.
184 linkstg:new[] asks you for a commit message when you create a new
185 patch, but as time goes by and you refresh the patch again and again,
186 chances are that the original commit message isn't quite correct
187 anymore. Fortunately, editing the commit message is very easy:
189 $ stg edit <patch-name>
191 In addition to linkstg:edit[], you can also give the +$$--edit$$+ flag
192 to linkstg:refresh[] -- that way, you get to change the commit message
193 and update the patch at the same time. Use whichever feels most
196 NOTE: linkstg:edit[] has a +$$--diff$$+ flag, which gives you the diff
197 text and not just the commit message in your editor. Be aware, though,
198 that if you change the diff so that it no longer applies, the edit
199 will be saved to a file instead of being carried out. If you're not
200 comfortable editing diffs, just treat +$$--diff$$+ as a way to get to
201 'see' the diff while you edit the commit message.
203 If the patch changes considerably, it might even deserve a new name.
204 linkstg:rename[] is your friend there.
210 Normally, when you pop a patch, change something, and then later push
211 it again, StGit sorts out everything for you automatically. For
212 example, let's create two patches that modify different files:
214 $ stg clone http://homepage.ntlworld.com/cmarinas/stgit.git stgit
216 $ stg new first --message 'First patch'
217 $ echo '- Do something' >> TODO
219 $ stg new second --message 'Second patch'
220 $ echo '- Install something' >> INSTALL
227 and then push them in the opposite order:
229 $ stg push second first
234 StGit had no problems reordering these patches for us, since they
235 didn't touch the same file. But it would have worked just fine even if
236 they had touched the same file, as long as they didn't change the same
237 part of the file. But what if they did? Let's find out.
240 Checking for changes in the working directory ... done
241 Popping patch "first" ... done
242 Now at patch "second"
243 $ echo '- Do something else' >> TODO
246 Now, both patches add a new line at the end of +TODO+. So what happens
247 when we try to have them both applied?
250 Pushing patch "first" ...
251 CONFLICT (content): Merge conflict in TODO
252 Error: The merge failed during "push".
253 Revert the operation with "stg undo".
254 stg push: 1 conflict(s)
256 StGit is telling us that it couldn't figure out how to push +first+ on
257 top of +second+, now that they both modify +TODO+. We can take a look
258 at the situation with linkstg:status[]:
266 As we were told by linkstg:push[], the conflict is in the file +TODO+.
267 (If the patch was bigger and touched multiple files, they would all be
268 listed here; prefixed with +C+ if they had conflicts, and +M+ if StGit
269 managed to automatically resolve everything in the file.)
271 NOTE: +TODO.ancestor+, +TODO.current+, and +TODO.patched+ are the
272 three versions of the file that StGit tried to merge. The +.current+
273 file is the version before the patch was applied, +.patched+ is the
274 version in the patch we tried to push, and +.ancestor+ the version
275 that contains neither of the added lines.
277 At this point, we have two options:
279 1. Undo the failed merge with linkstg:undo[]. (Remember to use the
280 +$$--hard$$+ flag, since the unresolved conflict means the
281 worktree is not clean.)
283 2. Manually resolve the conflict.
285 To resolve the conflict, open +TODO+ in your favorite editor. It ends
288 ----------------------------------------------------------------------
289 - numeric shortcuts for naming patches near top (eg. +1, -2)
290 - (config?) parameter for number of patches included by "series -s"
296 ----------------------------------------------------------------------
298 The 'conflict markers' +<<<<<<<+, +=======+, and +>>>>>>>+ indicate
299 which lines were already there (+current+) and which were added by the
300 patch (+patched+). Edit the file so that it looks like it should; in
301 this case, we want something like this:
303 ----------------------------------------------------------------------
304 - numeric shortcuts for naming patches near top (eg. +1, -2)
305 - (config?) parameter for number of patches included by "series -s"
308 ----------------------------------------------------------------------
310 Note that ``looks like it should'' includes removing the conflict
313 Now that we've resolved the conflict, we just need to tell StGit about
320 +TODO+ is listed as being modified, not in conflict. And we know from
321 before how to deal with modified files:
325 The conflict is now resolved. We can see that +first+ now looks a
326 little different; it no longer adds a line at the end of the file:
329 commit 8e3ae5f6fa6e9a5f831353524da5e0b91727338e
330 Author: Audrey U. Thor <author@example.com>
331 Date: Sun Oct 5 14:43:42 2008 +0200
335 diff --git a/TODO b/TODO
336 index 812d236..4ef3841 100644
339 @@ -24,4 +24,5 @@ The future, when time allows or if someone else does them:
340 they have scripts for moving the changes in one to the others)
341 - numeric shortcuts for naming patches near top (eg. +1, -2)
342 - (config?) parameter for number of patches included by "series -s"
347 Workflow: Development branch
348 ============================
350 One common use of StGit is to ``polish'' a Git branch before you
351 publish it for others to see. Such history falsification can often be
352 a 'good' thing -- when you (or someone else) needs to look at what you
353 did six months later, you are not really interested in all the false
354 starts and the steps needed to corect them. What you want is the final
355 solution, presented in a way that makes it easy to read and
358 Of course, there are limits. Editing the last few days' worth of
359 history is probably a good idea; editing the last few months' probably
360 isn't. A rule of thumb might be to not mess with history old enough
361 that you don't remember the details anymore. And rewriting history
362 that you have published for others to see (and base their own work on)
363 usually just makes everyone more confused, not less.
365 So, let's take a concrete example. Say that you're hacking on StGit,
366 and have made several Git commits as your work progressed, with commit
367 messages such as ``Improve the snarfle cache'', ``Remove debug
368 printout'', ``New snarfle cache test'', ``Oops, spell function name
369 correctly'', ``Fix documentation error'', and ``More snarfle cache''.
371 Now, this is the actual history, but for obvious reasons, this isn't
372 the kind of history you'd ideally want to find when you six months
373 from now try to figure out exactly where that elusive snarfle cache
374 bug was introduced. So let's turn this into the history we can be
375 proud of. The first step is to make StGit patches out of all those Git
378 $ stg uncommit --number 6
379 Uncommitting 6 patches ...
380 Now at patch "more-snarfle-cache"
382 $ stg series --description
383 + improve-the-snarfle-cache # Improve the snarfle cache
384 + remove-debug-printout # Remove debug printout
385 + new-snarfle-cache-test # New snarfle cache test
386 + oops-spell-function-name-corre # Oops, spell function name correctly
387 + fix-documentation-error # Fix documentation error
388 > more-snarfle-cache # More snarfle cache
390 As you can see, linkstg:uncommit[] adds StGit metadata to the last few
391 Git commits, turning them into StGit patches so that we can do stuff
394 NOTE: With the +$$--number$$+ flag, linkstg:uncommit[] uncommits that
395 many commits and generates names for them based on their commit
396 messages. If you like, you can instead list the patch names you want
399 At this point, there are a number of things we could do:
401 * Continue developing, and take advantage of e.g. linkstg:goto[] or
402 +stg refresh $$--patch$$+ to stick updates in the right patch to
405 * Use e.g. linkstg:float[], linkstg:sink[], linkstg:push[], and
406 linkstg:pop[] to reorder patches.
408 * Use linkstg:squash[] to merge two or more patches into one.
409 linkstgsub:squash[] pushes and pops so that the patches to be
410 merged are consecutive and unrelated patches aren't in the way,
411 then makes one big patch out of the patches to be merged, and
412 finally pushes the other patches back.
414 Of course, as always when there is pushing involved, there is the
415 possibility of conflicts. If a push results in a conflict, the
416 operation will be halted, and we'll be given the option of either
417 resolving the conflict or undoing.
419 Once we feel that the history is as good as it's going to get, we can
420 remove the StGit metadata, turning the patches back into regular Git
425 TIP: linkstg:commit[] can also commit specific patches (named on the
426 command line), leaving the rest alone. This can be used to retire
427 patches as they mature, while keeping the newer and more volatile
431 Workflow: Tracking branch
432 =========================
434 In the 'Development branch' workflow described above, we didn't have
435 to worry about other people; we're working on our branch, they are
436 presumably working on theirs, and when the time comes and we're ready
437 to publish our branch, we'll probably end up merging our branch with
438 those other peoples'. That's how Git is designed to work.
440 Or rather, one of the ways Git is designed to work. An alternative,
441 popular in e.g. the Linux kernel community (for which Git was
442 originally created), is that contributors send their patches by e-mail
443 to a mailing list. Others read the patches, try them out, and provide
444 feedback; often, the patch author is asked to send a new and improved
445 version of the patches. Once the project maintainer is satisfied that
446 the patches are good, she'll 'apply' them to a branch and publish it.
448 StGit is ideally suited for the process of creating patches, mailing
449 them out for review, revising them, mailing them off again, and
450 eventually getting them accepted.
453 Getting patches upstream
454 ------------------------
456 We've already covered how to clone a Git repository and start writing
457 patches. As for the next step, there are two commands you might use to
458 get patches out of StGit: linkstg:mail[] and linkstg:export[].
459 linkstg:export[] will export your patches to a filesystem directory as
460 one text file per patch, which can be useful if you are going to send
461 the patches by something other than e-mail. Most of the time, though,
462 linkstg:mail[] is what you want.
464 NOTE: Git comes with tools for sending commits via e-mail. Since StGit
465 patches are Git commits, you can use the Git tools if you like them
466 better for some reason.
468 NOTE: For exporting single patches -- as opposed to a whole bunch of
469 them -- you could also use linkstg:show[] or linkstg:diff[].
471 Mailing a patch is as easy as this:
473 $ stg mail --to recipient@example.com <patches>
475 You can list one or more patches, or ranges of patches. Each patch
476 will be sent as a separate mail, with the first line of the commit
477 message as subject line. Try mailing patches to yourself to see what
478 the result looks like.
480 NOTE: linkstg:mail[] uses +sendmail+ on your computer to send the
481 mails. If you don't have +sendmail+ properly set up, you can instruct
482 it to use any SMTP server with the +$$--smtp-server$$+ flag.
484 There are many command-line options to control exactly how mails are
485 sent, as well as a message template you can modify if you want. The
486 man page has all the details; I'll just mention two more here.
488 +$$--edit-cover$$+ will open an editor and let you write an
489 introductory message; all the patch mails will then be sent as replies
490 to this 'cover message'. This is usually a good idea if you send more
491 than one patch, so that reviewers can get a quick overview of the
494 +$$--edit-patches$$+ will let you edit each patch before it is sent.
495 You can change anything, but note that you are only editing the
496 outgoing mail, not the patch itself; if you want to make changes to
497 the patch, you probably want to use the regular StGit commands to do
498 so. What this 'is' useful for, though, is to add notes for the patch
501 ----------------------------------------------------------------------
502 From: Audrey U. Thor <author@example.com>
503 Subject: [PATCH] First line of the commit message
505 The rest of the commit message
509 Everything after the line with the three dashes and before the diff is
510 just a comment, and not part of the commit message. If there's
511 anything you want the patch recipients to see, but that shouldn't be
512 recorded in the history if the patch is accepted, write it here.
515 1 files changed, 1 insertions(+), 0 deletions(-)
518 diff --git a/stgit/main.py b/stgit/main.py
519 index e324179..6398958 100644
522 @@ -171,6 +171,7 @@ def _main():
523 sys.exit(ret or utils.STGIT_SUCCESS)
526 + print 'My first patch!'
530 ----------------------------------------------------------------------
533 Rebasing a patch series
534 -----------------------
536 While you are busy writing, submitting, and revising your patch
537 series, other people will be doing the same thing. As a result, even
538 though you started writing your patches on top of what was the latest
539 history at the time, your stack base will grow ever more out of date.
541 When you clone a repository,
543 $ stg clone http://homepage.ntlworld.com/cmarinas/stgit.git stgit
545 you initially get one local branch, +master+. You also get a number of
546 'remote' branches, one for each branch in the repository you cloned.
547 In the case of the StGit repository, these are
548 +remotes/origin/stable+, +remotes/origin/master+, and
549 +remotes/origin/proposed+. +remotes+ means that it's not a local
550 branch, just a snapshot of a branch in another repository; and
551 +origin+ is the default name for the first remote repository (you can
552 set up more; see the man page for +git remote+).
554 Right after cloning, +master+ and +remotes/origin/master+ point at the
555 same commit. When you start writing patches, +master+ will advance,
556 and always point at the current topmost patch, but
557 +remotes/origin/master+ will stay the same because it represents the
558 master branch in the repository you cloned from -- your 'upstream'
561 Unless you are the only one working on the project, however, the
562 upstream repository will not stay the same forever. New commits will
563 be added to its branches; to update your clone, run
567 This will update all your remote branches, but won't touch your local
568 branches. To get the latest changes into your local +master+ branch,
569 use linkstg:rebase[]:
571 $ stg rebase remotes/origin/master
573 This command will do three things:
575 1. Pop all patches, so that your local branch (+master+, in this
576 example) points at the stack base. This is the same commit that
577 +remotes/origin/master+ pointed at at the time you started
578 writing your patches.
580 2. Set the stack base to the given commit (the current, updated
581 value of +remotes/origin/master+).
583 3. Push the patches that were popped in the first step.
585 The end result is that your patches are now applied on top of the
586 latest version of +remotes/origin/master+.
588 The primary reason for rebasing is to reduce the amount of conflicts
589 between your work and others'. If one of your patches changes the same
590 part of the same file as a patch someone else has written, you will
591 get a conflict when you run linkstg:rebase[] the next time after the
592 other person's patch has been accepted upstream. It is almost always
593 less work to rebase often and resolve these one at a time, rather than
594 a whole lot at once. After all, you have to rebase eventually; if you
595 mail out patches that are based on an outdated branch, everyone who
596 tries to apply them has to resolve the conflicts instead. There are
597 more effective ways to get popular.
600 When your patches are accepted
601 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
603 If and when some or all of your patches are accepted upstream, you
604 update and rebase just like usual -- but be sure to use the
605 +$$--merged$$+ flag to linkstg:rebase[]:
608 $ stg rebase --merged remotes/origin/master
610 This flag makes the rebase operation better at detecting that your
611 patches have been merged, at some cost in performance.
613 The patches that had been merged will still be present in your patch
614 stack after the rebase, but they will be empty, since the change they
615 added is now already present in the stack base. Run linkstg:clean[] to
616 get rid of such empty patches if you don't want them hanging around:
624 While you are busy producing patches, there's hopefully someone -- the
625 'maintainer' -- at the other end who recieves them and 'applies' them
626 to her Git tree, which is then published for all (or parts of) the
629 It's perfectly fine for this person to not have the foggiest idea what
630 StGit is. In that case, she'll probably apply your patches with
631 something like +git am+, and everything will just work, exactly as if
632 you'd used Git to send those patches. But she might be an StGit user
633 too, in which case she might use linkstg:import[].
635 There are basically four kinds if stuff you can import with
638 1. A patch in a file.
640 2. Several files containing one patch each, and a 'series' file
641 listing those other files in the correct order.
643 3. An e-mail containing a single patch.
645 4. A mailbox file (in standard Unix +mbox+ format) containing
646 multiple e-mails with one patch in each.
649 Importing a plain patch
650 ~~~~~~~~~~~~~~~~~~~~~~~
652 Importing a plain patch, such as produced by e.g. GNU +diff+, +git
653 diff+, +git show+, linkstg:diff[], or linkstg:show[], is very easy.
656 $ stg import my-patch
658 and you'll have a new patch at the top of your stack.
660 If you don't give a file name on the command line, linkstg:import[]
661 will read the patch from its standard input -- in other words, you can
662 pipe a patch to it directly from the command that produces it.
664 By default, the new patch's name will be taken from the file name, and
665 its commit message and author info will be taken from the beginning of
666 the patch, if they are there. However, there are command line switches
667 to override all of these things; see the man page for details.
670 Importing several patches at once
671 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
673 Some programs -- among them linkstg:export[] -- will create a bunch of
674 files with one patch in each, and a 'series' file (often called
675 +series+) listing the other files in the correct order. Give
676 +$$--series$$+ and the name of the series file to linkstg:import[],
677 and it will import all the patches for you, in the correct order.
680 Importing a patch from an e-mail
681 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
683 Importing a patch from an e-mail is simple too:
685 $ stg import --mail my-mail
687 The e-mail should be in standard Git mail format (which is what e.g.
688 linkstg:mail[] produces) -- that is, with the patch in-line in the
689 mail, not attached. The authorship info is taken from the mail
690 headers, and the commit message is read from the 'Subject:' line and
693 If you don't give a file name, the mail will be read from the standard
694 input. This means that, if your mail reader supports it, you can pipe
695 a mail directly to +stg import $$--mail$$+ and the patch will be
699 Importing a mailbox full of patches
700 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
702 Finally, in case importing one patch at a time is too much work,
703 linkstg:import[] also accepts an entire Unix +mbox+-format mailbox,
704 either on the command line or on its standard input; just use the
705 +$$--mbox$$+ flag. Each mail should contain one patch, and is imported
706 just like with +$$--mail$$+.
708 Mailboxes full of patches are produced by e.g. linkstg:mail[] with the
709 +$$--mbox$$+ flag, but most mail readers can produce them too, meaning
710 that you can copy all the patch mails you want to apply to a separate
711 mailbox, and then import them all in one go.
714 Other stuff that needs to be placed somewhere
715 =============================================
721 TODO:: undo, redo, log, reset
724 Interoperating with Git
725 -----------------------
729 * git commit + repair
731 * git reset HEAD~n + repair
733 * don't do git rebase or git merge, because it won't work
739 TODO:: This section needs revising. I've only fixed the formatting.
740 Most of it should go under "Workflow: Tracking branch"
742 As mentioned in the introduction, StGit stores modifications to your
743 working tree in the form of Git commits. This means if you want to
744 apply your changes to a tree not managed by Git, or send your changes
745 to someone else in e-mail, you need to convert your StGit patches into
746 normal textual diffs that can be applied with the GNU patch command.
747 linkstg:diff[] is a powerful way to generate and view textual diffs of
748 patches managed by StGit.
750 To view a diff of the topmost patch:
754 Observe that this does not show any changes in the working directory
755 that have not been saved by a linkstgsub:refresh[]. To view just the
756 changes you've made since the last refresh, use:
760 If you want to see the changes made by the patch combined with any
761 unsaved changes in the working directory, try:
763 $ stg diff -r /bottom
765 You can also show the changes to any patch in your stack with:
767 $ stg diff -r <patch>/
769 Use this command to view all the changes in your stack up through the
774 linkstg:diff[] supports a number of other features that are very
775 useful. Be sure to take a look at the help information for this
776 command. To convert your StGit patches into patch files:
778 $ stg export [--range=[<patch1>[:<patch2>]]] [<dir-name>]
780 linkstg:export[] supports options to automatically number the patches
781 (+-n+) or add the +.diff+ extension (+-d+). If you don't tell
782 linkstgsub:export[] where to put the patches, it will create directory
783 named +patch-<branchname>+ in your current directory, and store the
784 patches there. To e-mail a patch or range of patches:
786 $ stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>)
788 linkstg:mail[] has a lot of options, so read the output of +stg mail
789 -h+ for more information.
791 You can also import an existing GNU diff patch file as a new StGit
792 patch with a single command. linkstg:import[] will automatically parse
793 through the patch file and extract a patch description. Use:
795 $ stg import [<file>]
797 This is the equivalent of
803 Sometimes the patch file won't apply cleanly. In that case,
804 linkstg:import[] will leave you with an empty StGit patch, to which
805 you then apply the patch file by hand using "patch -i" and your
808 To merge a GNU diff file (defaulting to the standard input) into the
813 This command supports a +$$--threeway$$+ option which applies the
814 patch onto the bottom of the topmost one and performs a three-way
821 TODO:: This section needs revising. I've only fixed the formatting.
823 linkstg:export[] and linkstg:mail[] use templates for generating the
824 patch files or e-mails. The default templates are installed under
825 +<prefix>/share/stgit/templates/+ and, combined with the extra options
826 available for these commands, should be enough for most users. The
827 template format uses the standard Python string formatting rules. The
828 variables available are listed in the the manual pages for each
829 command. linkstg:mail[] can also send an initial 'cover' e-mail for
830 which there is no default template. The
831 +<prefix>/share/stgit/examples/firstmail.tmpl+ file can be used as an
832 example. A default description for new patches can be defined in the
833 +.git/ patchdescr.tmpl+ file. This is useful for things like