Documentation: Rename link macros
[stgit] / Documentation / tutorial.txt
CommitLineData
ce0a1f86 1StGit tutorial
4625b604 2##############
d1c8fcd7 3
ce0a1f86
KH
4StGit is a command-line application that provides functionality
5similar to htmllink:http://savannah.nongnu.org/projects/quilt/[Quilt]
6(i.e. pushing/popping patches to/from a stack), but using Git instead
7of +diff+ and +patch+. StGit stores its patches in a Git repository as
8normal Git commits, and provides a number of commands to manipulate
9them in various ways.
d1c8fcd7 10
ce0a1f86
KH
11This tutorial assumes you are already familiar with the basics of Git
12(for example, branches, commits, and conflicts). For more information
13on Git, see manlink:git[1] or htmllink:http://git.or.cz/[the Git home
14page].
d1c8fcd7 15
d1c8fcd7 16
ce0a1f86
KH
17Help
18====
19
20For a full list of StGit commands:
21
22 $ stg help
23
24For quick help on individual subcommands:
25
26 $ stg help <cmd>
27
28For more extensive help on a subcommand:
29
30 $ man stg-<cmd>
31
32(The documentation is also available in htmllink:stg.html[HTML
33format].)
34
35
36Getting started
c2428e5a 37===============
d1c8fcd7 38
ce0a1f86
KH
39StGit is not a stand-alone program -- it operates on a Git repository
40that you have already created, using +git init+ or +git clone+. So get
41one of those; if you don't have one at hand, try for example
42
43 $ git clone http://homepage.ntlworld.com/cmarinas/stgit.git
44 $ cd stgit
d1c8fcd7 45
760a7cfc 46Before you can create StGit patches, you have to run linkstg:init[]:
d1c8fcd7 47
ce0a1f86 48 $ stg init
d1c8fcd7 49
ce0a1f86
KH
50This initializes the StGit metadata for the current branch. (So if you
51want to have StGit patches in another branch too, you need to run +stg
52init+ again in that branch.)
d1c8fcd7 53
760a7cfc 54NOTE: As a shortcut, linkstg:clone[] will run +git clone+ followed by
ce0a1f86 55+stg init+ for you.
d1c8fcd7 56
d1c8fcd7 57
ce0a1f86
KH
58Creating a patch
59----------------
d1c8fcd7 60
ce0a1f86 61Now we're ready to create our first patch:
d1c8fcd7 62
ce0a1f86 63 $ stg new my-first-patch
d1c8fcd7 64
ce0a1f86
KH
65This will create a patch called +my-first-patch+, and open an editor
66to let you edit the patch's commit message. (If you don't give a name
67on the command line, StGit will make one up based on the first line of
760a7cfc 68the commit message.) This patch is empty, as linkstg:show[] will tell
ce0a1f86 69you:
c2428e5a 70
ce0a1f86 71 $ stg show
c2428e5a 72
ce0a1f86
KH
73But it won't stay that way for long! Open one of the files in your
74favorite text editor, change something, and save. You now have some
75local changes in your tree:
c2428e5a 76
ce0a1f86
KH
77 $ stg status
78 M stgit/main.py
c2428e5a 79
760a7cfc 80Then linkstgsub:refresh[] the patch:
c2428e5a 81
ce0a1f86 82 $ stg refresh
d1c8fcd7 83
ce0a1f86 84And voilà -- the patch is no longer empty:
c2428e5a 85
ce0a1f86
KH
86 $ stg show
87 commit 3de32068c600d40d8af2a9cf1f1c762570ae9610
88 Author: Audrey U. Thor <author@example.com>
89 Date: Sat Oct 4 16:10:54 2008 +0200
c2428e5a 90
ce0a1f86 91 Tell the world that I've made a patch
d1c8fcd7 92
ce0a1f86
KH
93 diff --git a/stgit/main.py b/stgit/main.py
94 index e324179..6398958 100644
95 --- a/stgit/main.py
96 +++ b/stgit/main.py
97 @@ -171,6 +171,7 @@ def _main():
98 sys.exit(ret or utils.STGIT_SUCCESS)
d1c8fcd7 99
ce0a1f86
KH
100 def main():
101 + print 'My first patch!'
102 try:
103 _main()
104 finally:
d1c8fcd7 105
58e2aed2
KH
106(I'm assuming you're already familiar with
107htmllink:http://en.wikipedia.org/wiki/Diff#Unified_format[unified
108diff] patches like this from Git, but it's really quite simple; in
109this example, I've added the +$$print 'My first patch!'$$+ line to the
110file +stgit/main.py+, at around line 171.)
c2428e5a 111
ce0a1f86
KH
112Since the patch is also a regular Git commit, you can also look at it
113with regular Git tools such as manlink:gitk[].
d1c8fcd7 114
ce0a1f86
KH
115Creating another patch
116----------------------
c2428e5a 117
ce0a1f86
KH
118We want to make another improvement, so let's create a new patch for
119it:
d1c8fcd7 120
ce0a1f86
KH
121 $ echo 'Audrey U. Thor' > AUTHORS
122 $ stg new credit --message 'Give me some credit'
123 $ stg refresh
d1c8fcd7 124
ce0a1f86 125Note that we can give the commit message on the command line, and that
760a7cfc 126it doesn't matter whether we run linkstg:new[] before or after we edit
ce0a1f86 127the files.
d1c8fcd7 128
ce0a1f86 129So now we have two patches:
d1c8fcd7 130
ce0a1f86
KH
131 $ stg series --description
132 + my-first-patch # This is my first patch
133 > credit # Give me some credit
d1c8fcd7 134
760a7cfc 135linkstg:series[] lists the patches from bottom to top; +$$+$$+ means
ce0a1f86
KH
136that a patch is 'applied', and +>+ that it is the 'current', or
137topmost, patch.
d1c8fcd7 138
ce0a1f86
KH
139If we want to make further changes to the topmost patch, we just edit
140the files and run +stg refresh+. But what if we wanted to change
760a7cfc 141+my-first-patch+? The simplest way is to linkstgsub:pop[] the +credit+
ce0a1f86 142patch, so that +my-first-patch+ becomes topmost again:
d1c8fcd7 143
ce0a1f86
KH
144 $ stg pop credit
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
d1c8fcd7 151
760a7cfc
KH
152linkstg:series[] now shows that +my-first-patch+ is topmost again,
153which means that linkstg:refresh[] will update it with any changes we
ce0a1f86 154make.
d1c8fcd7 155
ce0a1f86
KH
156The minus sign says that +credit+ is 'unapplied' -- this means that
157it's been temporarily put aside. If you look at the +AUTHORS+ file,
158you'll see that our change to it is gone; and tools such as
159manlink:gitk[] will not show it, because it's been edited out of the
760a7cfc 160Git history. But it's just one linkstg:push[] command away from being
ce0a1f86 161restored:
d1c8fcd7 162
ce0a1f86
KH
163 $ stg push credit
164 Checking for changes in the working directory ... done
165 Fast-forwarded patch "credit"
166 Now at patch "credit"
d1c8fcd7 167
760a7cfc
KH
168NOTE: You can omit the patch name argument to linkstg:push[] and
169linkstg:pop[]. If you do, you will push the next unapplied patch, and
ce0a1f86 170pop the topmost patch, respectively.
c2428e5a 171
ce0a1f86 172NOTE: There are at least two more ways to update a non-topmost patch.
760a7cfc 173One is to use linkstg:refresh[] with the +$$--patch$$+ flag, the other
ce0a1f86 174to create a new patch for the update and then merge it into the other
760a7cfc 175patch with linkstg:squash[].
c2428e5a 176
18eec969 177
ce0a1f86
KH
178Keeping commit messages up to date
179----------------------------------
18eec969 180
ce0a1f86
KH
181Since StGit is all about creating readable Git history (or a readable
182patch series, which is essentially the same thing), one thing you'll
183want to pay attention to is the commit messages of your patches.
760a7cfc 184linkstg:new[] asks you for a commit message when you create a new
ce0a1f86
KH
185patch, but as time goes by and you refresh the patch again and again,
186chances are that the original commit message isn't quite correct
187anymore. Fortunately, editing the commit message is very easy:
188
189 $ stg edit <patch-name>
190
760a7cfc
KH
191In addition to linkstg:edit[], you can also give the +$$--edit$$+ flag
192to linkstg:refresh[] -- that way, you get to change the commit message
ce0a1f86
KH
193and update the patch at the same time. Use whichever feels most
194natural to you.
195
760a7cfc 196NOTE: linkstg:edit[] has a +$$--diff$$+ flag, which gives you the diff
ce0a1f86
KH
197text and not just the commit message in your editor. Be aware, though,
198that if you change the diff so that it no longer applies, the edit
199will be saved to a file instead of being carried out. If you're not
200comfortable editing diffs, just treat +$$--diff$$+ as a way to get to
201'see' the diff while you edit the commit message.
202
203If the patch changes considerably, it might even deserve a new name.
760a7cfc 204linkstg:rename[] is your friend there.
18eec969 205
c2428e5a 206
ce0a1f86
KH
207Conflicts
208---------
209
210Normally, when you pop a patch, change something, and then later push
211it again, StGit sorts out everything for you automatically. For
212example, let's create two patches that modify different files:
213
214 $ stg clone http://homepage.ntlworld.com/cmarinas/stgit.git stgit
215 $ cd stgit
216 $ stg new first --message 'First patch'
217 $ echo '- Do something' >> TODO
218 $ stg refresh
219 $ stg new second --message 'Second patch'
220 $ echo '- Install something' >> INSTALL
221 $ stg refresh
222
223then pop them both:
224
225 $ stg pop --all
226
227and then push them in the opposite order:
228
229 $ stg push second first
230 $ stg series
231 + second
232 > first
233
234StGit had no problems reordering these patches for us, since they
235didn't touch the same file. But it would have worked just fine even if
236they had touched the same file, as long as they didn't change the same
237part of the file. But what if they did? Let's find out.
238
239 $ stg pop
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
244 $ stg refresh
245
246Now, both patches add a new line at the end of +TODO+. So what happens
247when we try to have them both applied?
248
249 $ stg push
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)
255
256StGit is telling us that it couldn't figure out how to push +first+ on
257top of +second+, now that they both modify +TODO+. We can take a look
760a7cfc 258at the situation with linkstg:status[]:
ce0a1f86
KH
259
260 $ stg status
261 ? TODO.ancestor
262 ? TODO.current
263 ? TODO.patched
264 C TODO
265
760a7cfc 266As we were told by linkstg:push[], the conflict is in the file +TODO+.
ce0a1f86
KH
267(If the patch was bigger and touched multiple files, they would all be
268listed here; prefixed with +C+ if they had conflicts, and +M+ if StGit
269managed to automatically resolve everything in the file.)
270
271NOTE: +TODO.ancestor+, +TODO.current+, and +TODO.patched+ are the
272three versions of the file that StGit tried to merge. The +.current+
273file is the version before the patch was applied, +.patched+ is the
274version in the patch we tried to push, and +.ancestor+ the version
275that contains neither of the added lines.
276
277At this point, we have two options:
278
760a7cfc 279 1. Undo the failed merge with linkstg:undo[]. (Remember to use the
ce0a1f86
KH
280 +$$--hard$$+ flag, since the unresolved conflict means the
281 worktree is not clean.)
282
283 2. Manually resolve the conflict.
284
285To resolve the conflict, open +TODO+ in your favorite editor. It ends
286like this:
287
288----------------------------------------------------------------------
289- numeric shortcuts for naming patches near top (eg. +1, -2)
290- (config?) parameter for number of patches included by "series -s"
291<<<<<<< current:TODO
292- Do something else
293=======
294- Do something
295>>>>>>> patched:TODO
296----------------------------------------------------------------------
297
298The 'conflict markers' +<<<<<<<+, +=======+, and +>>>>>>>+ indicate
299which lines were already there (+current+) and which were added by the
300patch (+patched+). Edit the file so that it looks like it should; in
301this case, we want something like this:
302
303----------------------------------------------------------------------
304- numeric shortcuts for naming patches near top (eg. +1, -2)
305- (config?) parameter for number of patches included by "series -s"
306- Do something
307- Do something else
308----------------------------------------------------------------------
309
310Note that ``looks like it should'' includes removing the conflict
311markers.
312
313Now that we've resolved the conflict, we just need to tell StGit about
314it:
315
316 $ stg resolved TODO
317 $ stg status
318 M TODO
319
320+TODO+ is listed as being modified, not in conflict. And we know from
321before how to deal with modified files:
322
323 $ stg refresh
324
325The conflict is now resolved. We can see that +first+ now looks a
326little different; it no longer adds a line at the end of the file:
327
328 $ stg show
329 commit 8e3ae5f6fa6e9a5f831353524da5e0b91727338e
330 Author: Audrey U. Thor <author@example.com>
331 Date: Sun Oct 5 14:43:42 2008 +0200
332
333 First patch
334
335 diff --git a/TODO b/TODO
336 index 812d236..4ef3841 100644
337 --- a/TODO
338 +++ b/TODO
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"
343 +- Do something
344 - Do something else
345
346
347Workflow: Development branch
348============================
349
350One common use of StGit is to ``polish'' a Git branch before you
351publish it for others to see. Such history falsification can often be
352a 'good' thing -- when you (or someone else) needs to look at what you
353did six months later, you are not really interested in all the false
354starts and the steps needed to corect them. What you want is the final
355solution, presented in a way that makes it easy to read and
356understand.
357
358Of course, there are limits. Editing the last few days' worth of
359history is probably a good idea; editing the last few months' probably
360isn't. A rule of thumb might be to not mess with history old enough
361that you don't remember the details anymore. And rewriting history
362that you have published for others to see (and base their own work on)
363usually just makes everyone more confused, not less.
364
365So, let's take a concrete example. Say that you're hacking on StGit,
366and have made several Git commits as your work progressed, with commit
367messages such as ``Improve the snarfle cache'', ``Remove debug
368printout'', ``New snarfle cache test'', ``Oops, spell function name
369correctly'', ``Fix documentation error'', and ``More snarfle cache''.
370
371Now, this is the actual history, but for obvious reasons, this isn't
372the kind of history you'd ideally want to find when you six months
373from now try to figure out exactly where that elusive snarfle cache
374bug was introduced. So let's turn this into the history we can be
375proud of. The first step is to make StGit patches out of all those Git
376commits:
377
378 $ stg uncommit --number 6
379 Uncommitting 6 patches ...
380 Now at patch "more-snarfle-cache"
381 done
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
389
760a7cfc 390As you can see, linkstg:uncommit[] adds StGit metadata to the last few
ce0a1f86
KH
391Git commits, turning them into StGit patches so that we can do stuff
392with them.
393
760a7cfc 394NOTE: With the +$$--number$$+ flag, linkstg:uncommit[] uncommits that
ce0a1f86
KH
395many commits and generates names for them based on their commit
396messages. If you like, you can instead list the patch names you want
397on the command line.
398
399At this point, there are a number of things we could do:
400
760a7cfc 401 * Continue developing, and take advantage of e.g. linkstg:goto[] or
ce0a1f86
KH
402 +stg refresh $$--patch$$+ to stick updates in the right patch to
403 begin with.
404
760a7cfc
KH
405 * Use e.g. linkstg:float[], linkstg:sink[], linkstg:push[], and
406 linkstg:pop[] to reorder patches.
ce0a1f86 407
760a7cfc
KH
408 * Use linkstg:squash[] to merge two or more patches into one.
409 linkstgsub:squash[] pushes and pops so that the patches to be
ce0a1f86
KH
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.
413+
414Of course, as always when there is pushing involved, there is the
415possibility of conflicts. If a push results in a conflict, the
416operation will be halted, and we'll be given the option of either
417resolving the conflict or undoing.
418
419Once we feel that the history is as good as it's going to get, we can
420remove the StGit metadata, turning the patches back into regular Git
421commits again:
422
423 $ stg commit --all
424
760a7cfc 425TIP: linkstg:commit[] can also commit specific patches (named on the
ce0a1f86
KH
426command line), leaving the rest alone. This can be used to retire
427patches as they mature, while keeping the newer and more volatile
428patches as patches.
429
430
431Workflow: Tracking branch
432=========================
433
e1bec2d5
KH
434In the 'Development branch' workflow described above, we didn't have
435to worry about other people; we're working on our branch, they are
436presumably working on theirs, and when the time comes and we're ready
437to publish our branch, we'll probably end up merging our branch with
438those other peoples'. That's how Git is designed to work.
ce0a1f86 439
e1bec2d5
KH
440Or rather, one of the ways Git is designed to work. An alternative,
441popular in e.g. the Linux kernel community (for which Git was
442originally created), is that contributors send their patches by e-mail
443to a mailing list. Others read the patches, try them out, and provide
444feedback; often, the patch author is asked to send a new and improved
445version of the patches. Once the project maintainer is satisfied that
446the patches are good, she'll 'apply' them to a branch and publish it.
ce0a1f86 447
e1bec2d5
KH
448StGit is ideally suited for the process of creating patches, mailing
449them out for review, revising them, mailing them off again, and
450eventually getting them accepted.
ce0a1f86
KH
451
452
453Getting patches upstream
454------------------------
455
e1bec2d5
KH
456We've already covered how to clone a Git repository and start writing
457patches. As for the next step, there are two commands you might use to
760a7cfc
KH
458get patches out of StGit: linkstg:mail[] and linkstg:export[].
459linkstg:export[] will export your patches to a filesystem directory as
e1bec2d5
KH
460one text file per patch, which can be useful if you are going to send
461the patches by something other than e-mail. Most of the time, though,
760a7cfc 462linkstg:mail[] is what you want.
e1bec2d5
KH
463
464NOTE: Git comes with tools for sending commits via e-mail. Since StGit
465patches are Git commits, you can use the Git tools if you like them
466better for some reason.
467
468NOTE: For exporting single patches -- as opposed to a whole bunch of
760a7cfc 469them -- you could also use linkstg:show[] or linkstg:diff[].
e1bec2d5
KH
470
471Mailing a patch is as easy as this:
472
473 $ stg mail --to recipient@example.com <patches>
474
475You can list one or more patches, or ranges of patches. Each patch
476will be sent as a separate mail, with the first line of the commit
477message as subject line. Try mailing patches to yourself to see what
478the result looks like.
479
760a7cfc 480NOTE: linkstg:mail[] uses +sendmail+ on your computer to send the
e1bec2d5
KH
481mails. If you don't have +sendmail+ properly set up, you can instruct
482it to use any SMTP server with the +$$--smtp-server$$+ flag.
483
484There are many command-line options to control exactly how mails are
485sent, as well as a message template you can modify if you want. The
486man page has all the details; I'll just mention two more here.
487
488+$$--edit-cover$$+ will open an editor and let you write an
489introductory message; all the patch mails will then be sent as replies
490to this 'cover message'. This is usually a good idea if you send more
491than one patch, so that reviewers can get a quick overview of the
492patches you sent.
493
494+$$--edit-patches$$+ will let you edit each patch before it is sent.
495You can change anything, but note that you are only editing the
496outgoing mail, not the patch itself; if you want to make changes to
497the patch, you probably want to use the regular StGit commands to do
498so. What this 'is' useful for, though, is to add notes for the patch
499recipients:
500
501----------------------------------------------------------------------
502From: Audrey U. Thor <author@example.com>
503Subject: [PATCH] First line of the commit message
504
505The rest of the commit message
506
507---
508
509Everything after the line with the three dashes and before the diff is
510just a comment, and not part of the commit message. If there's
511anything you want the patch recipients to see, but that shouldn't be
512recorded in the history if the patch is accepted, write it here.
513
514 stgit/main.py | 1 +
515 1 files changed, 1 insertions(+), 0 deletions(-)
516
517
518diff --git a/stgit/main.py b/stgit/main.py
519index e324179..6398958 100644
520--- a/stgit/main.py
521+++ b/stgit/main.py
522@@ -171,6 +171,7 @@ def _main():
523 sys.exit(ret or utils.STGIT_SUCCESS)
524
525 def main():
526+ print 'My first patch!'
527 try:
528 _main()
529 finally:
530----------------------------------------------------------------------
531
532
533Rebasing a patch series
534-----------------------
535
2b5462d7
KH
536While you are busy writing, submitting, and revising your patch
537series, other people will be doing the same thing. As a result, even
538though you started writing your patches on top of what was the latest
539history at the time, your stack base will grow ever more out of date.
540
541When you clone a repository,
542
543 $ stg clone http://homepage.ntlworld.com/cmarinas/stgit.git stgit
544
545you initially get one local branch, +master+. You also get a number of
546'remote' branches, one for each branch in the repository you cloned.
547In 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
550branch, just a snapshot of a branch in another repository; and
551+origin+ is the default name for the first remote repository (you can
552set up more; see the man page for +git remote+).
553
554Right after cloning, +master+ and +remotes/origin/master+ point at the
555same commit. When you start writing patches, +master+ will advance,
556and always point at the current topmost patch, but
557+remotes/origin/master+ will stay the same because it represents the
558master branch in the repository you cloned from -- your 'upstream'
559repository.
560
561Unless you are the only one working on the project, however, the
562upstream repository will not stay the same forever. New commits will
563be added to its branches; to update your clone, run
564
565 $ git remote update
566
567This will update all your remote branches, but won't touch your local
568branches. To get the latest changes into your local +master+ branch,
760a7cfc 569use linkstg:rebase[]:
2b5462d7
KH
570
571 $ stg rebase remotes/origin/master
572
573This command will do three things:
574
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.
579
580 2. Set the stack base to the given commit (the current, updated
581 value of +remotes/origin/master+).
582
583 3. Push the patches that were popped in the first step.
584
585The end result is that your patches are now applied on top of the
586latest version of +remotes/origin/master+.
587
588The primary reason for rebasing is to reduce the amount of conflicts
589between your work and others'. If one of your patches changes the same
590part of the same file as a patch someone else has written, you will
760a7cfc 591get a conflict when you run linkstg:rebase[] the next time after the
2b5462d7
KH
592other person's patch has been accepted upstream. It is almost always
593less work to rebase often and resolve these one at a time, rather than
594a whole lot at once. After all, you have to rebase eventually; if you
595mail out patches that are based on an outdated branch, everyone who
596tries to apply them has to resolve the conflicts instead. There are
597more effective ways to get popular.
598
599
600When your patches are accepted
601~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
602
603If and when some or all of your patches are accepted upstream, you
604update and rebase just like usual -- but be sure to use the
760a7cfc 605+$$--merged$$+ flag to linkstg:rebase[]:
2b5462d7
KH
606
607 $ git remote update
608 $ stg rebase --merged remotes/origin/master
609
610This flag makes the rebase operation better at detecting that your
611patches have been merged, at some cost in performance.
612
613The patches that had been merged will still be present in your patch
614stack after the rebase, but they will be empty, since the change they
760a7cfc 615added is now already present in the stack base. Run linkstg:clean[] to
2b5462d7
KH
616get rid of such empty patches if you don't want them hanging around:
617
618 $ stg clean
c2428e5a 619
c2428e5a 620
ce0a1f86
KH
621Importing patches
622-----------------
c2428e5a 623
fc552485
KH
624While you are busy producing patches, there's hopefully someone -- the
625'maintainer' -- at the other end who recieves them and 'applies' them
626to her Git tree, which is then published for all (or parts of) the
627world to see.
628
629It's perfectly fine for this person to not have the foggiest idea what
630StGit is. In that case, she'll probably apply your patches with
631something like +git am+, and everything will just work, exactly as if
632you'd used Git to send those patches. But she might be an StGit user
760a7cfc 633too, in which case she might use linkstg:import[].
fc552485
KH
634
635There are basically four kinds if stuff you can import with
760a7cfc 636linkstg:import[]:
fc552485
KH
637
638 1. A patch in a file.
639
640 2. Several files containing one patch each, and a 'series' file
641 listing those other files in the correct order.
642
643 3. An e-mail containing a single patch.
644
645 4. A mailbox file (in standard Unix +mbox+ format) containing
646 multiple e-mails with one patch in each.
647
648
649Importing a plain patch
650~~~~~~~~~~~~~~~~~~~~~~~
651
652Importing a plain patch, such as produced by e.g. GNU +diff+, +git
760a7cfc 653diff+, +git show+, linkstg:diff[], or linkstg:show[], is very easy.
fc552485
KH
654Just say
655
656 $ stg import my-patch
657
658and you'll have a new patch at the top of your stack.
659
760a7cfc 660If you don't give a file name on the command line, linkstg:import[]
fc552485
KH
661will read the patch from its standard input -- in other words, you can
662pipe a patch to it directly from the command that produces it.
663
664By default, the new patch's name will be taken from the file name, and
665its commit message and author info will be taken from the beginning of
666the patch, if they are there. However, there are command line switches
667to override all of these things; see the man page for details.
668
669
670Importing several patches at once
671^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
672
760a7cfc 673Some programs -- among them linkstg:export[] -- will create a bunch of
fc552485
KH
674files with one patch in each, and a 'series' file (often called
675+series+) listing the other files in the correct order. Give
760a7cfc 676+$$--series$$+ and the name of the series file to linkstg:import[],
fc552485
KH
677and it will import all the patches for you, in the correct order.
678
679
680Importing a patch from an e-mail
681~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
682
683Importing a patch from an e-mail is simple too:
684
685 $ stg import --mail my-mail
686
687The e-mail should be in standard Git mail format (which is what e.g.
760a7cfc 688linkstg:mail[] produces) -- that is, with the patch in-line in the
fc552485
KH
689mail, not attached. The authorship info is taken from the mail
690headers, and the commit message is read from the 'Subject:' line and
691the mail body.
692
693If you don't give a file name, the mail will be read from the standard
694input. This means that, if your mail reader supports it, you can pipe
695a mail directly to +stg import $$--mail$$+ and the patch will be
696applied.
697
698
699Importing a mailbox full of patches
700^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
701
702Finally, in case importing one patch at a time is too much work,
760a7cfc 703linkstg:import[] also accepts an entire Unix +mbox+-format mailbox,
fc552485
KH
704either on the command line or on its standard input; just use the
705+$$--mbox$$+ flag. Each mail should contain one patch, and is imported
706just like with +$$--mail$$+.
707
760a7cfc 708Mailboxes full of patches are produced by e.g. linkstg:mail[] with the
fc552485
KH
709+$$--mbox$$+ flag, but most mail readers can produce them too, meaning
710that you can copy all the patch mails you want to apply to a separate
711mailbox, and then import them all in one go.
c2428e5a 712
c2428e5a 713
ce0a1f86
KH
714Other stuff that needs to be placed somewhere
715=============================================
716
717
718Undo
719----
d1c8fcd7 720
ce0a1f86 721TODO:: undo, redo, log, reset
d1c8fcd7 722
d1c8fcd7 723
ce0a1f86
KH
724Interoperating with Git
725-----------------------
d1c8fcd7 726
ce0a1f86 727TODO::
d1c8fcd7 728
ce0a1f86 729* git commit + repair
d1c8fcd7 730
ce0a1f86 731* git reset HEAD~n + repair
d1c8fcd7 732
ce0a1f86 733* don't do git rebase or git merge, because it won't work
d1c8fcd7 734
d1c8fcd7 735
ce0a1f86
KH
736Patch stuff
737-----------
d1c8fcd7 738
ce0a1f86
KH
739TODO:: This section needs revising. I've only fixed the formatting.
740Most of it should go under "Workflow: Tracking branch"
741
742As mentioned in the introduction, StGit stores modifications to your
743working tree in the form of Git commits. This means if you want to
744apply your changes to a tree not managed by Git, or send your changes
745to someone else in e-mail, you need to convert your StGit patches into
746normal textual diffs that can be applied with the GNU patch command.
760a7cfc 747linkstg:diff[] is a powerful way to generate and view textual diffs of
ce0a1f86 748patches managed by StGit.
d1c8fcd7 749
c2428e5a 750To view a diff of the topmost patch:
d1c8fcd7 751
ce0a1f86 752 $ stg diff -r /
d1c8fcd7 753
c2428e5a 754Observe that this does not show any changes in the working directory
760a7cfc 755that have not been saved by a linkstgsub:refresh[]. To view just the
ce0a1f86 756changes you've made since the last refresh, use:
d1c8fcd7 757
ce0a1f86 758 $ stg diff -r /top
d1c8fcd7 759
c2428e5a
CM
760If you want to see the changes made by the patch combined with any
761unsaved changes in the working directory, try:
d1c8fcd7 762
ce0a1f86 763 $ stg diff -r /bottom
d1c8fcd7 764
c2428e5a 765You can also show the changes to any patch in your stack with:
d1c8fcd7 766
ce0a1f86 767 $ stg diff -r <patch>/
d1c8fcd7 768
c2428e5a
CM
769Use this command to view all the changes in your stack up through the
770current patch:
771
ce0a1f86 772 $ stg diff -r base
d1c8fcd7 773
760a7cfc 774linkstg:diff[] supports a number of other features that are very
ce0a1f86
KH
775useful. Be sure to take a look at the help information for this
776command. To convert your StGit patches into patch files:
d1c8fcd7 777
ce0a1f86 778 $ stg export [--range=[<patch1>[:<patch2>]]] [<dir-name>]
d1c8fcd7 779
760a7cfc 780linkstg:export[] supports options to automatically number the patches
ce0a1f86 781(+-n+) or add the +.diff+ extension (+-d+). If you don't tell
760a7cfc 782linkstgsub:export[] where to put the patches, it will create directory
ce0a1f86
KH
783named +patch-<branchname>+ in your current directory, and store the
784patches there. To e-mail a patch or range of patches:
c2428e5a 785
ce0a1f86 786 $ stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>)
c2428e5a 787
760a7cfc 788linkstg:mail[] has a lot of options, so read the output of +stg mail
ce0a1f86 789-h+ for more information.
c2428e5a 790
ce0a1f86 791You can also import an existing GNU diff patch file as a new StGit
760a7cfc 792patch with a single command. linkstg:import[] will automatically parse
ce0a1f86 793through the patch file and extract a patch description. Use:
d1c8fcd7 794
ce0a1f86 795 $ stg import [<file>]
d1c8fcd7 796
ce0a1f86 797This is the equivalent of
d1c8fcd7 798
ce0a1f86
KH
799 $ stg new
800 $ patch -i <file>
801 $ stg refresh -e
d1c8fcd7 802
ce0a1f86 803Sometimes the patch file won't apply cleanly. In that case,
760a7cfc 804linkstg:import[] will leave you with an empty StGit patch, to which
ce0a1f86
KH
805you then apply the patch file by hand using "patch -i" and your
806favorite editor.
d1c8fcd7 807
ce0a1f86
KH
808To merge a GNU diff file (defaulting to the standard input) into the
809topmost patch:
d1c8fcd7 810
ce0a1f86 811 $ stg fold [<file>]
c2428e5a 812
ce0a1f86
KH
813This command supports a +$$--threeway$$+ option which applies the
814patch onto the bottom of the topmost one and performs a three-way
815merge.
27373fe0 816
c2428e5a 817
27373fe0
CM
818Templates
819---------
d1c8fcd7 820
ce0a1f86
KH
821TODO:: This section needs revising. I've only fixed the formatting.
822
760a7cfc 823linkstg:export[] and linkstg:mail[] use templates for generating the
ce0a1f86
KH
824patch files or e-mails. The default templates are installed under
825+<prefix>/share/stgit/templates/+ and, combined with the extra options
826available for these commands, should be enough for most users. The
827template format uses the standard Python string formatting rules. The
828variables available are listed in the the manual pages for each
760a7cfc 829command. linkstg:mail[] can also send an initial 'cover' e-mail for
ce0a1f86
KH
830which there is no default template. The
831+<prefix>/share/stgit/examples/firstmail.tmpl+ file can be used as an
832example. A default description for new patches can be defined in the
833+.git/ patchdescr.tmpl+ file. This is useful for things like
834signed-off-by lines.