Commit | Line | Data |
---|---|---|
ce0a1f86 | 1 | StGit tutorial |
4625b604 | 2 | ############## |
d1c8fcd7 | 3 | |
ce0a1f86 KH |
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 | |
9 | them in various ways. | |
d1c8fcd7 | 10 | |
ce0a1f86 KH |
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 | |
14 | page]. | |
d1c8fcd7 | 15 | |
d1c8fcd7 | 16 | |
ce0a1f86 KH |
17 | Help |
18 | ==== | |
19 | ||
20 | For a full list of StGit commands: | |
21 | ||
22 | $ stg help | |
23 | ||
24 | For quick help on individual subcommands: | |
25 | ||
26 | $ stg help <cmd> | |
27 | ||
28 | For more extensive help on a subcommand: | |
29 | ||
30 | $ man stg-<cmd> | |
31 | ||
32 | (The documentation is also available in htmllink:stg.html[HTML | |
33 | format].) | |
34 | ||
35 | ||
36 | Getting started | |
c2428e5a | 37 | =============== |
d1c8fcd7 | 38 | |
ce0a1f86 KH |
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 | |
42 | ||
43 | $ git clone http://homepage.ntlworld.com/cmarinas/stgit.git | |
44 | $ cd stgit | |
d1c8fcd7 | 45 | |
ce0a1f86 | 46 | Before you can create StGit patches, you have to run stglink:init[]: |
d1c8fcd7 | 47 | |
ce0a1f86 | 48 | $ stg init |
d1c8fcd7 | 49 | |
ce0a1f86 KH |
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.) | |
d1c8fcd7 | 53 | |
ce0a1f86 KH |
54 | NOTE: As a shortcut, stglink:clone[] will run +git clone+ followed by |
55 | +stg init+ for you. | |
d1c8fcd7 | 56 | |
d1c8fcd7 | 57 | |
ce0a1f86 KH |
58 | Creating a patch |
59 | ---------------- | |
d1c8fcd7 | 60 | |
ce0a1f86 | 61 | Now we're ready to create our first patch: |
d1c8fcd7 | 62 | |
ce0a1f86 | 63 | $ stg new my-first-patch |
d1c8fcd7 | 64 | |
ce0a1f86 KH |
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 | |
69 | you: | |
c2428e5a | 70 | |
ce0a1f86 | 71 | $ stg show |
c2428e5a | 72 | |
ce0a1f86 KH |
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: | |
c2428e5a | 76 | |
ce0a1f86 KH |
77 | $ stg status |
78 | M stgit/main.py | |
c2428e5a | 79 | |
ce0a1f86 | 80 | Then stgsublink:refresh[] the patch: |
c2428e5a | 81 | |
ce0a1f86 | 82 | $ stg refresh |
d1c8fcd7 | 83 | |
ce0a1f86 | 84 | And 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 |
107 | htmllink: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.) | |
c2428e5a | 111 | |
ce0a1f86 KH |
112 | Since the patch is also a regular Git commit, you can also look at it |
113 | with regular Git tools such as manlink:gitk[]. | |
d1c8fcd7 | 114 | |
ce0a1f86 KH |
115 | Creating another patch |
116 | ---------------------- | |
c2428e5a | 117 | |
ce0a1f86 KH |
118 | We want to make another improvement, so let's create a new patch for |
119 | it: | |
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 KH |
125 | Note that we can give the commit message on the command line, and that |
126 | it doesn't matter whether we run stglink:new[] before or after we edit | |
127 | the files. | |
d1c8fcd7 | 128 | |
ce0a1f86 | 129 | So 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 | |
ce0a1f86 KH |
135 | stglink:series[] lists the patches from bottom to top; +$$+$$+ means |
136 | that a patch is 'applied', and +>+ that it is the 'current', or | |
137 | topmost, patch. | |
d1c8fcd7 | 138 | |
ce0a1f86 KH |
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 stgsublink:pop[] the +credit+ | |
142 | patch, 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 | |
ce0a1f86 KH |
152 | stglink:series[] now shows that +my-first-patch+ is topmost again, |
153 | which means that stglink:refresh[] will update it with any changes we | |
154 | make. | |
d1c8fcd7 | 155 | |
ce0a1f86 KH |
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 | manlink:gitk[] will not show it, because it's been edited out of the | |
160 | Git history. But it's just one stglink:push[] command away from being | |
161 | restored: | |
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 | |
ce0a1f86 KH |
168 | NOTE: You can omit the patch name argument to stglink:push[] and |
169 | stglink:pop[]. If you do, you will push the next unapplied patch, and | |
170 | pop the topmost patch, respectively. | |
c2428e5a | 171 | |
ce0a1f86 KH |
172 | NOTE: There are at least two more ways to update a non-topmost patch. |
173 | One is to use stglink: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 stglink:coalesce[]. | |
c2428e5a | 176 | |
18eec969 | 177 | |
ce0a1f86 KH |
178 | Keeping commit messages up to date |
179 | ---------------------------------- | |
18eec969 | 180 | |
ce0a1f86 KH |
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 | stglink: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: | |
188 | ||
189 | $ stg edit <patch-name> | |
190 | ||
191 | In addition to stglink:edit[], you can also give the +$$--edit$$+ flag | |
192 | to stglink:refresh[] -- that way, you get to change the commit message | |
193 | and update the patch at the same time. Use whichever feels most | |
194 | natural to you. | |
195 | ||
196 | NOTE: stglink: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. | |
202 | ||
203 | If the patch changes considerably, it might even deserve a new name. | |
204 | stglink:rename[] is your friend there. | |
18eec969 | 205 | |
c2428e5a | 206 | |
ce0a1f86 KH |
207 | Conflicts |
208 | --------- | |
209 | ||
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: | |
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 | ||
223 | then pop them both: | |
224 | ||
225 | $ stg pop --all | |
226 | ||
227 | and then push them in the opposite order: | |
228 | ||
229 | $ stg push second first | |
230 | $ stg series | |
231 | + second | |
232 | > first | |
233 | ||
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. | |
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 | ||
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? | |
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 | ||
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 stglink:status[]: | |
259 | ||
260 | $ stg status | |
261 | ? TODO.ancestor | |
262 | ? TODO.current | |
263 | ? TODO.patched | |
264 | C TODO | |
265 | ||
266 | As we were told by stglink: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.) | |
270 | ||
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. | |
276 | ||
277 | At this point, we have two options: | |
278 | ||
279 | 1. Undo the failed merge with stglink:undo[]. (Remember to use the | |
280 | +$$--hard$$+ flag, since the unresolved conflict means the | |
281 | worktree is not clean.) | |
282 | ||
283 | 2. Manually resolve the conflict. | |
284 | ||
285 | To resolve the conflict, open +TODO+ in your favorite editor. It ends | |
286 | like 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 | ||
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: | |
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 | ||
310 | Note that ``looks like it should'' includes removing the conflict | |
311 | markers. | |
312 | ||
313 | Now that we've resolved the conflict, we just need to tell StGit about | |
314 | it: | |
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 | |
321 | before how to deal with modified files: | |
322 | ||
323 | $ stg refresh | |
324 | ||
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: | |
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 | ||
347 | Workflow: Development branch | |
348 | ============================ | |
349 | ||
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 | |
356 | understand. | |
357 | ||
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. | |
364 | ||
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''. | |
370 | ||
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 | |
376 | commits: | |
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 | ||
390 | As you can see, stglink:uncommit[] adds StGit metadata to the last few | |
391 | Git commits, turning them into StGit patches so that we can do stuff | |
392 | with them. | |
393 | ||
394 | NOTE: With the +$$--number$$+ flag, stglink: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 | |
397 | on the command line. | |
398 | ||
399 | At this point, there are a number of things we could do: | |
400 | ||
401 | * Continue developing, and take advantage of e.g. stglink:goto[] or | |
402 | +stg refresh $$--patch$$+ to stick updates in the right patch to | |
403 | begin with. | |
404 | ||
405 | * Use e.g. stglink:float[], stglink:sink[], stglink:push[], and | |
406 | stglink:pop[] to reorder patches. | |
407 | ||
408 | * Use stglink:coalesce[] to merge two or more patches into one. | |
409 | stgsublink:coalesce[] 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. | |
413 | + | |
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. | |
418 | ||
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 | |
421 | commits again: | |
422 | ||
423 | $ stg commit --all | |
424 | ||
425 | TIP: stglink: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 | |
428 | patches as patches. | |
429 | ||
430 | ||
431 | Workflow: Tracking branch | |
432 | ========================= | |
433 | ||
434 | ||
435 | Rebasing a patch series | |
436 | ----------------------- | |
437 | ||
438 | TODO:: rebase, ... | |
439 | ||
440 | ||
441 | Getting patches upstream | |
442 | ------------------------ | |
443 | ||
444 | TODO:: export, mail, ... | |
c2428e5a | 445 | |
c2428e5a | 446 | |
ce0a1f86 KH |
447 | Importing patches |
448 | ----------------- | |
c2428e5a | 449 | |
ce0a1f86 | 450 | TODO:: import, ... |
c2428e5a | 451 | |
c2428e5a | 452 | |
ce0a1f86 KH |
453 | Other stuff that needs to be placed somewhere |
454 | ============================================= | |
455 | ||
456 | ||
457 | Undo | |
458 | ---- | |
d1c8fcd7 | 459 | |
ce0a1f86 | 460 | TODO:: undo, redo, log, reset |
d1c8fcd7 | 461 | |
d1c8fcd7 | 462 | |
ce0a1f86 KH |
463 | Interoperating with Git |
464 | ----------------------- | |
d1c8fcd7 | 465 | |
ce0a1f86 | 466 | TODO:: |
d1c8fcd7 | 467 | |
ce0a1f86 | 468 | * git commit + repair |
d1c8fcd7 | 469 | |
ce0a1f86 | 470 | * git reset HEAD~n + repair |
d1c8fcd7 | 471 | |
ce0a1f86 | 472 | * don't do git rebase or git merge, because it won't work |
d1c8fcd7 | 473 | |
d1c8fcd7 | 474 | |
ce0a1f86 KH |
475 | Patch stuff |
476 | ----------- | |
d1c8fcd7 | 477 | |
ce0a1f86 KH |
478 | TODO:: This section needs revising. I've only fixed the formatting. |
479 | Most of it should go under "Workflow: Tracking branch" | |
480 | ||
481 | As mentioned in the introduction, StGit stores modifications to your | |
482 | working tree in the form of Git commits. This means if you want to | |
483 | apply your changes to a tree not managed by Git, or send your changes | |
484 | to someone else in e-mail, you need to convert your StGit patches into | |
485 | normal textual diffs that can be applied with the GNU patch command. | |
486 | stglink:diff[] is a powerful way to generate and view textual diffs of | |
487 | patches managed by StGit. | |
d1c8fcd7 | 488 | |
c2428e5a | 489 | To view a diff of the topmost patch: |
d1c8fcd7 | 490 | |
ce0a1f86 | 491 | $ stg diff -r / |
d1c8fcd7 | 492 | |
c2428e5a | 493 | Observe that this does not show any changes in the working directory |
ce0a1f86 KH |
494 | that have not been saved by a stgsublink:refresh[]. To view just the |
495 | changes you've made since the last refresh, use: | |
d1c8fcd7 | 496 | |
ce0a1f86 | 497 | $ stg diff -r /top |
d1c8fcd7 | 498 | |
c2428e5a CM |
499 | If you want to see the changes made by the patch combined with any |
500 | unsaved changes in the working directory, try: | |
d1c8fcd7 | 501 | |
ce0a1f86 | 502 | $ stg diff -r /bottom |
d1c8fcd7 | 503 | |
c2428e5a | 504 | You can also show the changes to any patch in your stack with: |
d1c8fcd7 | 505 | |
ce0a1f86 | 506 | $ stg diff -r <patch>/ |
d1c8fcd7 | 507 | |
c2428e5a CM |
508 | Use this command to view all the changes in your stack up through the |
509 | current patch: | |
510 | ||
ce0a1f86 | 511 | $ stg diff -r base |
d1c8fcd7 | 512 | |
ce0a1f86 KH |
513 | stglink:diff[] supports a number of other features that are very |
514 | useful. Be sure to take a look at the help information for this | |
515 | command. To convert your StGit patches into patch files: | |
d1c8fcd7 | 516 | |
ce0a1f86 | 517 | $ stg export [--range=[<patch1>[:<patch2>]]] [<dir-name>] |
d1c8fcd7 | 518 | |
ce0a1f86 KH |
519 | stglink:export[] supports options to automatically number the patches |
520 | (+-n+) or add the +.diff+ extension (+-d+). If you don't tell | |
521 | stgsublink:export[] where to put the patches, it will create directory | |
522 | named +patch-<branchname>+ in your current directory, and store the | |
523 | patches there. To e-mail a patch or range of patches: | |
c2428e5a | 524 | |
ce0a1f86 | 525 | $ stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>) |
c2428e5a | 526 | |
ce0a1f86 KH |
527 | stglink:mail[] has a lot of options, so read the output of +stg mail |
528 | -h+ for more information. | |
c2428e5a | 529 | |
ce0a1f86 KH |
530 | You can also import an existing GNU diff patch file as a new StGit |
531 | patch with a single command. stglink:import[] will automatically parse | |
532 | through the patch file and extract a patch description. Use: | |
d1c8fcd7 | 533 | |
ce0a1f86 | 534 | $ stg import [<file>] |
d1c8fcd7 | 535 | |
ce0a1f86 | 536 | This is the equivalent of |
d1c8fcd7 | 537 | |
ce0a1f86 KH |
538 | $ stg new |
539 | $ patch -i <file> | |
540 | $ stg refresh -e | |
d1c8fcd7 | 541 | |
ce0a1f86 KH |
542 | Sometimes the patch file won't apply cleanly. In that case, |
543 | stglink:import[] will leave you with an empty StGit patch, to which | |
544 | you then apply the patch file by hand using "patch -i" and your | |
545 | favorite editor. | |
d1c8fcd7 | 546 | |
ce0a1f86 KH |
547 | To merge a GNU diff file (defaulting to the standard input) into the |
548 | topmost patch: | |
d1c8fcd7 | 549 | |
ce0a1f86 | 550 | $ stg fold [<file>] |
c2428e5a | 551 | |
ce0a1f86 KH |
552 | This command supports a +$$--threeway$$+ option which applies the |
553 | patch onto the bottom of the topmost one and performs a three-way | |
554 | merge. | |
27373fe0 | 555 | |
c2428e5a | 556 | |
27373fe0 CM |
557 | Templates |
558 | --------- | |
d1c8fcd7 | 559 | |
ce0a1f86 KH |
560 | TODO:: This section needs revising. I've only fixed the formatting. |
561 | ||
562 | stglink:export[] and stglink:mail[] use templates for generating the | |
563 | patch files or e-mails. The default templates are installed under | |
564 | +<prefix>/share/stgit/templates/+ and, combined with the extra options | |
565 | available for these commands, should be enough for most users. The | |
566 | template format uses the standard Python string formatting rules. The | |
567 | variables available are listed in the the manual pages for each | |
568 | command. stglink:mail[] can also send an initial 'cover' e-mail for | |
569 | which there is no default template. The | |
570 | +<prefix>/share/stgit/examples/firstmail.tmpl+ file can be used as an | |
571 | example. A default description for new patches can be defined in the | |
572 | +.git/ patchdescr.tmpl+ file. This is useful for things like | |
573 | signed-off-by lines. |