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 | ||
e1bec2d5 KH |
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. | |
ce0a1f86 | 439 | |
e1bec2d5 KH |
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. | |
ce0a1f86 | 447 | |
e1bec2d5 KH |
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. | |
ce0a1f86 KH |
451 | |
452 | ||
453 | Getting patches upstream | |
454 | ------------------------ | |
455 | ||
e1bec2d5 KH |
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: stglink:mail[] and stglink:export[]. | |
459 | stglink: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 | stglink:mail[] is what you want. | |
463 | ||
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. | |
467 | ||
468 | NOTE: For exporting single patches -- as opposed to a whole bunch of | |
469 | them -- you could also use stglink:show[] or stglink:diff[]. | |
470 | ||
471 | Mailing a patch is as easy as this: | |
472 | ||
473 | $ stg mail --to recipient@example.com <patches> | |
474 | ||
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. | |
479 | ||
480 | NOTE: stglink: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. | |
483 | ||
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. | |
487 | ||
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 | |
492 | patches you sent. | |
493 | ||
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 | |
499 | recipients: | |
500 | ||
501 | ---------------------------------------------------------------------- | |
502 | From: Audrey U. Thor <author@example.com> | |
503 | Subject: [PATCH] First line of the commit message | |
504 | ||
505 | The rest of the commit message | |
506 | ||
507 | --- | |
508 | ||
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. | |
513 | ||
514 | stgit/main.py | 1 + | |
515 | 1 files changed, 1 insertions(+), 0 deletions(-) | |
516 | ||
517 | ||
518 | diff --git a/stgit/main.py b/stgit/main.py | |
519 | index 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 | ||
533 | Rebasing a patch series | |
534 | ----------------------- | |
535 | ||
2b5462d7 KH |
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. | |
540 | ||
541 | When you clone a repository, | |
542 | ||
543 | $ stg clone http://homepage.ntlworld.com/cmarinas/stgit.git stgit | |
544 | ||
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+). | |
553 | ||
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' | |
559 | repository. | |
560 | ||
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 | |
564 | ||
565 | $ git remote update | |
566 | ||
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 stglink:rebase[]: | |
570 | ||
571 | $ stg rebase remotes/origin/master | |
572 | ||
573 | This 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 | ||
585 | The end result is that your patches are now applied on top of the | |
586 | latest version of +remotes/origin/master+. | |
587 | ||
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 stglink: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. | |
598 | ||
599 | ||
600 | When your patches are accepted | |
601 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
602 | ||
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 stglink:rebase[]: | |
606 | ||
607 | $ git remote update | |
608 | $ stg rebase --merged remotes/origin/master | |
609 | ||
610 | This flag makes the rebase operation better at detecting that your | |
611 | patches have been merged, at some cost in performance. | |
612 | ||
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 stglink:clean[] to | |
616 | get rid of such empty patches if you don't want them hanging around: | |
617 | ||
618 | $ stg clean | |
c2428e5a | 619 | |
c2428e5a | 620 | |
ce0a1f86 KH |
621 | Importing patches |
622 | ----------------- | |
c2428e5a | 623 | |
fc552485 KH |
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 | |
627 | world to see. | |
628 | ||
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 stglink:import[]. | |
634 | ||
635 | There are basically four kinds if stuff you can import with | |
636 | stglink:import[]: | |
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 | ||
649 | Importing a plain patch | |
650 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
651 | ||
652 | Importing a plain patch, such as produced by e.g. GNU +diff+, +git | |
653 | diff+, +git show+, stglink:diff[], or stglink:show[], is very easy. | |
654 | Just say | |
655 | ||
656 | $ stg import my-patch | |
657 | ||
658 | and you'll have a new patch at the top of your stack. | |
659 | ||
660 | If you don't give a file name on the command line, stglink: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. | |
663 | ||
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. | |
668 | ||
669 | ||
670 | Importing several patches at once | |
671 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
672 | ||
673 | Some programs -- among them stglink: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 stglink:import[], | |
677 | and it will import all the patches for you, in the correct order. | |
678 | ||
679 | ||
680 | Importing a patch from an e-mail | |
681 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
682 | ||
683 | Importing a patch from an e-mail is simple too: | |
684 | ||
685 | $ stg import --mail my-mail | |
686 | ||
687 | The e-mail should be in standard Git mail format (which is what e.g. | |
688 | stglink: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 | |
691 | the mail body. | |
692 | ||
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 | |
696 | applied. | |
697 | ||
698 | ||
699 | Importing a mailbox full of patches | |
700 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
701 | ||
702 | Finally, in case importing one patch at a time is too much work, | |
703 | stglink: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$$+. | |
707 | ||
708 | Mailboxes full of patches are produced by e.g. stglink: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. | |
c2428e5a | 712 | |
c2428e5a | 713 | |
ce0a1f86 KH |
714 | Other stuff that needs to be placed somewhere |
715 | ============================================= | |
716 | ||
717 | ||
718 | Undo | |
719 | ---- | |
d1c8fcd7 | 720 | |
ce0a1f86 | 721 | TODO:: undo, redo, log, reset |
d1c8fcd7 | 722 | |
d1c8fcd7 | 723 | |
ce0a1f86 KH |
724 | Interoperating with Git |
725 | ----------------------- | |
d1c8fcd7 | 726 | |
ce0a1f86 | 727 | TODO:: |
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 |
736 | Patch stuff |
737 | ----------- | |
d1c8fcd7 | 738 | |
ce0a1f86 KH |
739 | TODO:: This section needs revising. I've only fixed the formatting. |
740 | Most of it should go under "Workflow: Tracking branch" | |
741 | ||
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 | stglink:diff[] is a powerful way to generate and view textual diffs of | |
748 | patches managed by StGit. | |
d1c8fcd7 | 749 | |
c2428e5a | 750 | To view a diff of the topmost patch: |
d1c8fcd7 | 751 | |
ce0a1f86 | 752 | $ stg diff -r / |
d1c8fcd7 | 753 | |
c2428e5a | 754 | Observe that this does not show any changes in the working directory |
ce0a1f86 KH |
755 | that have not been saved by a stgsublink:refresh[]. To view just the |
756 | changes you've made since the last refresh, use: | |
d1c8fcd7 | 757 | |
ce0a1f86 | 758 | $ stg diff -r /top |
d1c8fcd7 | 759 | |
c2428e5a CM |
760 | If you want to see the changes made by the patch combined with any |
761 | unsaved changes in the working directory, try: | |
d1c8fcd7 | 762 | |
ce0a1f86 | 763 | $ stg diff -r /bottom |
d1c8fcd7 | 764 | |
c2428e5a | 765 | You can also show the changes to any patch in your stack with: |
d1c8fcd7 | 766 | |
ce0a1f86 | 767 | $ stg diff -r <patch>/ |
d1c8fcd7 | 768 | |
c2428e5a CM |
769 | Use this command to view all the changes in your stack up through the |
770 | current patch: | |
771 | ||
ce0a1f86 | 772 | $ stg diff -r base |
d1c8fcd7 | 773 | |
ce0a1f86 KH |
774 | stglink: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: | |
d1c8fcd7 | 777 | |
ce0a1f86 | 778 | $ stg export [--range=[<patch1>[:<patch2>]]] [<dir-name>] |
d1c8fcd7 | 779 | |
ce0a1f86 KH |
780 | stglink:export[] supports options to automatically number the patches |
781 | (+-n+) or add the +.diff+ extension (+-d+). If you don't tell | |
782 | stgsublink: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: | |
c2428e5a | 785 | |
ce0a1f86 | 786 | $ stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>) |
c2428e5a | 787 | |
ce0a1f86 KH |
788 | stglink:mail[] has a lot of options, so read the output of +stg mail |
789 | -h+ for more information. | |
c2428e5a | 790 | |
ce0a1f86 KH |
791 | You can also import an existing GNU diff patch file as a new StGit |
792 | patch with a single command. stglink:import[] will automatically parse | |
793 | through the patch file and extract a patch description. Use: | |
d1c8fcd7 | 794 | |
ce0a1f86 | 795 | $ stg import [<file>] |
d1c8fcd7 | 796 | |
ce0a1f86 | 797 | This is the equivalent of |
d1c8fcd7 | 798 | |
ce0a1f86 KH |
799 | $ stg new |
800 | $ patch -i <file> | |
801 | $ stg refresh -e | |
d1c8fcd7 | 802 | |
ce0a1f86 KH |
803 | Sometimes the patch file won't apply cleanly. In that case, |
804 | stglink: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 | |
806 | favorite editor. | |
d1c8fcd7 | 807 | |
ce0a1f86 KH |
808 | To merge a GNU diff file (defaulting to the standard input) into the |
809 | topmost patch: | |
d1c8fcd7 | 810 | |
ce0a1f86 | 811 | $ stg fold [<file>] |
c2428e5a | 812 | |
ce0a1f86 KH |
813 | This command supports a +$$--threeway$$+ option which applies the |
814 | patch onto the bottom of the topmost one and performs a three-way | |
815 | merge. | |
27373fe0 | 816 | |
c2428e5a | 817 | |
27373fe0 CM |
818 | Templates |
819 | --------- | |
d1c8fcd7 | 820 | |
ce0a1f86 KH |
821 | TODO:: This section needs revising. I've only fixed the formatting. |
822 | ||
823 | stglink:export[] and stglink: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. stglink: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 | |
834 | signed-off-by lines. |