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 | |
ce0a1f86 KH |
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 | |
109 | 171.) | |
c2428e5a | 110 | |
ce0a1f86 KH |
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[]. | |
d1c8fcd7 | 113 | |
ce0a1f86 KH |
114 | Creating another patch |
115 | ---------------------- | |
c2428e5a | 116 | |
ce0a1f86 KH |
117 | We want to make another improvement, so let's create a new patch for |
118 | it: | |
d1c8fcd7 | 119 | |
ce0a1f86 KH |
120 | $ echo 'Audrey U. Thor' > AUTHORS |
121 | $ stg new credit --message 'Give me some credit' | |
122 | $ stg refresh | |
d1c8fcd7 | 123 | |
ce0a1f86 KH |
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 | |
126 | the files. | |
d1c8fcd7 | 127 | |
ce0a1f86 | 128 | So now we have two patches: |
d1c8fcd7 | 129 | |
ce0a1f86 KH |
130 | $ stg series --description |
131 | + my-first-patch # This is my first patch | |
132 | > credit # Give me some credit | |
d1c8fcd7 | 133 | |
ce0a1f86 KH |
134 | stglink:series[] lists the patches from bottom to top; +$$+$$+ means |
135 | that a patch is 'applied', and +>+ that it is the 'current', or | |
136 | topmost, patch. | |
d1c8fcd7 | 137 | |
ce0a1f86 KH |
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: | |
d1c8fcd7 | 142 | |
ce0a1f86 KH |
143 | $ stg pop credit |
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 | |
d1c8fcd7 | 150 | |
ce0a1f86 KH |
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 | |
153 | make. | |
d1c8fcd7 | 154 | |
ce0a1f86 KH |
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 | |
160 | restored: | |
d1c8fcd7 | 161 | |
ce0a1f86 KH |
162 | $ stg push credit |
163 | Checking for changes in the working directory ... done | |
164 | Fast-forwarded patch "credit" | |
165 | Now at patch "credit" | |
d1c8fcd7 | 166 | |
ce0a1f86 KH |
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. | |
c2428e5a | 170 | |
ce0a1f86 KH |
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[]. | |
c2428e5a | 175 | |
18eec969 | 176 | |
ce0a1f86 KH |
177 | Keeping commit messages up to date |
178 | ---------------------------------- | |
18eec969 | 179 | |
ce0a1f86 KH |
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: | |
187 | ||
188 | $ stg edit <patch-name> | |
189 | ||
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 | |
193 | natural to you. | |
194 | ||
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. | |
201 | ||
202 | If the patch changes considerably, it might even deserve a new name. | |
203 | stglink:rename[] is your friend there. | |
18eec969 | 204 | |
c2428e5a | 205 | |
ce0a1f86 KH |
206 | Conflicts |
207 | --------- | |
208 | ||
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: | |
212 | ||
213 | $ stg clone http://homepage.ntlworld.com/cmarinas/stgit.git stgit | |
214 | $ cd stgit | |
215 | $ stg new first --message 'First patch' | |
216 | $ echo '- Do something' >> TODO | |
217 | $ stg refresh | |
218 | $ stg new second --message 'Second patch' | |
219 | $ echo '- Install something' >> INSTALL | |
220 | $ stg refresh | |
221 | ||
222 | then pop them both: | |
223 | ||
224 | $ stg pop --all | |
225 | ||
226 | and then push them in the opposite order: | |
227 | ||
228 | $ stg push second first | |
229 | $ stg series | |
230 | + second | |
231 | > first | |
232 | ||
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. | |
237 | ||
238 | $ stg pop | |
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 | |
243 | $ stg refresh | |
244 | ||
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? | |
247 | ||
248 | $ stg push | |
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) | |
254 | ||
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[]: | |
258 | ||
259 | $ stg status | |
260 | ? TODO.ancestor | |
261 | ? TODO.current | |
262 | ? TODO.patched | |
263 | C TODO | |
264 | ||
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.) | |
269 | ||
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. | |
275 | ||
276 | At this point, we have two options: | |
277 | ||
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.) | |
281 | ||
282 | 2. Manually resolve the conflict. | |
283 | ||
284 | To resolve the conflict, open +TODO+ in your favorite editor. It ends | |
285 | like this: | |
286 | ||
287 | ---------------------------------------------------------------------- | |
288 | - numeric shortcuts for naming patches near top (eg. +1, -2) | |
289 | - (config?) parameter for number of patches included by "series -s" | |
290 | <<<<<<< current:TODO | |
291 | - Do something else | |
292 | ======= | |
293 | - Do something | |
294 | >>>>>>> patched:TODO | |
295 | ---------------------------------------------------------------------- | |
296 | ||
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: | |
301 | ||
302 | ---------------------------------------------------------------------- | |
303 | - numeric shortcuts for naming patches near top (eg. +1, -2) | |
304 | - (config?) parameter for number of patches included by "series -s" | |
305 | - Do something | |
306 | - Do something else | |
307 | ---------------------------------------------------------------------- | |
308 | ||
309 | Note that ``looks like it should'' includes removing the conflict | |
310 | markers. | |
311 | ||
312 | Now that we've resolved the conflict, we just need to tell StGit about | |
313 | it: | |
314 | ||
315 | $ stg resolved TODO | |
316 | $ stg status | |
317 | M TODO | |
318 | ||
319 | +TODO+ is listed as being modified, not in conflict. And we know from | |
320 | before how to deal with modified files: | |
321 | ||
322 | $ stg refresh | |
323 | ||
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: | |
326 | ||
327 | $ stg show | |
328 | commit 8e3ae5f6fa6e9a5f831353524da5e0b91727338e | |
329 | Author: Audrey U. Thor <author@example.com> | |
330 | Date: Sun Oct 5 14:43:42 2008 +0200 | |
331 | ||
332 | First patch | |
333 | ||
334 | diff --git a/TODO b/TODO | |
335 | index 812d236..4ef3841 100644 | |
336 | --- a/TODO | |
337 | +++ b/TODO | |
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" | |
342 | +- Do something | |
343 | - Do something else | |
344 | ||
345 | ||
346 | Workflow: Development branch | |
347 | ============================ | |
348 | ||
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 | |
355 | understand. | |
356 | ||
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. | |
363 | ||
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''. | |
369 | ||
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 | |
375 | commits: | |
376 | ||
377 | $ stg uncommit --number 6 | |
378 | Uncommitting 6 patches ... | |
379 | Now at patch "more-snarfle-cache" | |
380 | done | |
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 | |
388 | ||
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 | |
391 | with them. | |
392 | ||
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 | |
396 | on the command line. | |
397 | ||
398 | At this point, there are a number of things we could do: | |
399 | ||
400 | * Continue developing, and take advantage of e.g. stglink:goto[] or | |
401 | +stg refresh $$--patch$$+ to stick updates in the right patch to | |
402 | begin with. | |
403 | ||
404 | * Use e.g. stglink:float[], stglink:sink[], stglink:push[], and | |
405 | stglink:pop[] to reorder patches. | |
406 | ||
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. | |
412 | + | |
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. | |
417 | ||
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 | |
420 | commits again: | |
421 | ||
422 | $ stg commit --all | |
423 | ||
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 | |
427 | patches as patches. | |
428 | ||
429 | ||
430 | Workflow: Tracking branch | |
431 | ========================= | |
432 | ||
433 | ||
434 | Rebasing a patch series | |
435 | ----------------------- | |
436 | ||
437 | TODO:: rebase, ... | |
438 | ||
439 | ||
440 | Getting patches upstream | |
441 | ------------------------ | |
442 | ||
443 | TODO:: export, mail, ... | |
c2428e5a | 444 | |
c2428e5a | 445 | |
ce0a1f86 KH |
446 | Importing patches |
447 | ----------------- | |
c2428e5a | 448 | |
ce0a1f86 | 449 | TODO:: import, ... |
c2428e5a | 450 | |
c2428e5a | 451 | |
ce0a1f86 KH |
452 | Other stuff that needs to be placed somewhere |
453 | ============================================= | |
454 | ||
455 | ||
456 | Undo | |
457 | ---- | |
d1c8fcd7 | 458 | |
ce0a1f86 | 459 | TODO:: undo, redo, log, reset |
d1c8fcd7 | 460 | |
d1c8fcd7 | 461 | |
ce0a1f86 KH |
462 | Interoperating with Git |
463 | ----------------------- | |
d1c8fcd7 | 464 | |
ce0a1f86 | 465 | TODO:: |
d1c8fcd7 | 466 | |
ce0a1f86 | 467 | * git commit + repair |
d1c8fcd7 | 468 | |
ce0a1f86 | 469 | * git reset HEAD~n + repair |
d1c8fcd7 | 470 | |
ce0a1f86 | 471 | * don't do git rebase or git merge, because it won't work |
d1c8fcd7 | 472 | |
d1c8fcd7 | 473 | |
ce0a1f86 KH |
474 | Patch stuff |
475 | ----------- | |
d1c8fcd7 | 476 | |
ce0a1f86 KH |
477 | TODO:: This section needs revising. I've only fixed the formatting. |
478 | Most of it should go under "Workflow: Tracking branch" | |
479 | ||
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. | |
d1c8fcd7 | 487 | |
c2428e5a | 488 | To view a diff of the topmost patch: |
d1c8fcd7 | 489 | |
ce0a1f86 | 490 | $ stg diff -r / |
d1c8fcd7 | 491 | |
c2428e5a | 492 | Observe that this does not show any changes in the working directory |
ce0a1f86 KH |
493 | that have not been saved by a stgsublink:refresh[]. To view just the |
494 | changes you've made since the last refresh, use: | |
d1c8fcd7 | 495 | |
ce0a1f86 | 496 | $ stg diff -r /top |
d1c8fcd7 | 497 | |
c2428e5a CM |
498 | If you want to see the changes made by the patch combined with any |
499 | unsaved changes in the working directory, try: | |
d1c8fcd7 | 500 | |
ce0a1f86 | 501 | $ stg diff -r /bottom |
d1c8fcd7 | 502 | |
c2428e5a | 503 | You can also show the changes to any patch in your stack with: |
d1c8fcd7 | 504 | |
ce0a1f86 | 505 | $ stg diff -r <patch>/ |
d1c8fcd7 | 506 | |
c2428e5a CM |
507 | Use this command to view all the changes in your stack up through the |
508 | current patch: | |
509 | ||
ce0a1f86 | 510 | $ stg diff -r base |
d1c8fcd7 | 511 | |
ce0a1f86 KH |
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: | |
d1c8fcd7 | 515 | |
ce0a1f86 | 516 | $ stg export [--range=[<patch1>[:<patch2>]]] [<dir-name>] |
d1c8fcd7 | 517 | |
ce0a1f86 KH |
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: | |
c2428e5a | 523 | |
ce0a1f86 | 524 | $ stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>) |
c2428e5a | 525 | |
ce0a1f86 KH |
526 | stglink:mail[] has a lot of options, so read the output of +stg mail |
527 | -h+ for more information. | |
c2428e5a | 528 | |
ce0a1f86 KH |
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: | |
d1c8fcd7 | 532 | |
ce0a1f86 | 533 | $ stg import [<file>] |
d1c8fcd7 | 534 | |
ce0a1f86 | 535 | This is the equivalent of |
d1c8fcd7 | 536 | |
ce0a1f86 KH |
537 | $ stg new |
538 | $ patch -i <file> | |
539 | $ stg refresh -e | |
d1c8fcd7 | 540 | |
ce0a1f86 KH |
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 | |
544 | favorite editor. | |
d1c8fcd7 | 545 | |
ce0a1f86 KH |
546 | To merge a GNU diff file (defaulting to the standard input) into the |
547 | topmost patch: | |
d1c8fcd7 | 548 | |
ce0a1f86 | 549 | $ stg fold [<file>] |
c2428e5a | 550 | |
ce0a1f86 KH |
551 | This command supports a +$$--threeway$$+ option which applies the |
552 | patch onto the bottom of the topmost one and performs a three-way | |
553 | merge. | |
27373fe0 | 554 | |
c2428e5a | 555 | |
27373fe0 CM |
556 | Templates |
557 | --------- | |
d1c8fcd7 | 558 | |
ce0a1f86 KH |
559 | TODO:: This section needs revising. I've only fixed the formatting. |
560 | ||
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 | |
572 | signed-off-by lines. |