Commit | Line | Data |
---|---|---|
ce0a1f86 | 1 | StGit tutorial |
4625b604 | 2 | ############## |
d1c8fcd7 | 3 | |
ce0a1f86 | 4 | StGit is a command-line application that provides functionality |
9777fa36 | 5 | similar to link:http://savannah.nongnu.org/projects/quilt/[Quilt] |
ce0a1f86 KH |
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 | |
9777fa36 | 13 | on Git, see linkman:git[1] or link:http://git.or.cz/[the Git home |
ce0a1f86 | 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 | ||
9777fa36 | 32 | (The documentation is also available in link:stg.html[HTML |
ce0a1f86 KH |
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 | ||
6a458ad8 | 43 | $ git clone git://repo.or.cz/stgit.git |
ce0a1f86 | 44 | $ cd stgit |
d1c8fcd7 | 45 | |
760a7cfc | 46 | Before you can create StGit patches, you have to run linkstg: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 | |
760a7cfc | 54 | NOTE: As a shortcut, linkstg:clone[] will run +git clone+ followed by |
ce0a1f86 | 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 | |
760a7cfc | 68 | the commit message.) This patch is empty, as linkstg:show[] will tell |
ce0a1f86 | 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 | |
760a7cfc | 80 | Then linkstgsub: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 | 106 | (I'm assuming you're already familiar with |
9777fa36 | 107 | link:http://en.wikipedia.org/wiki/Diff#Unified_format[unified |
58e2aed2 KH |
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 | 112 | Since the patch is also a regular Git commit, you can also look at it |
9777fa36 | 113 | with regular Git tools such as linkman: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 | 125 | Note that we can give the commit message on the command line, and that |
760a7cfc | 126 | it doesn't matter whether we run linkstg:new[] before or after we edit |
ce0a1f86 | 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 | |
760a7cfc | 135 | linkstg:series[] lists the patches from bottom to top; +$$+$$+ means |
ce0a1f86 KH |
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 | |
760a7cfc | 141 | +my-first-patch+? The simplest way is to linkstgsub:pop[] the +credit+ |
ce0a1f86 | 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 | |
760a7cfc KH |
152 | linkstg:series[] now shows that +my-first-patch+ is topmost again, |
153 | which means that linkstg:refresh[] will update it with any changes we | |
ce0a1f86 | 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 | |
9777fa36 | 159 | linkman:gitk[] will not show it, because it's been edited out of the |
760a7cfc | 160 | Git history. But it's just one linkstg:push[] command away from being |
ce0a1f86 | 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 | |
760a7cfc KH |
168 | NOTE: You can omit the patch name argument to linkstg:push[] and |
169 | linkstg:pop[]. If you do, you will push the next unapplied patch, and | |
ce0a1f86 | 170 | pop the topmost patch, respectively. |
c2428e5a | 171 | |
ce0a1f86 | 172 | NOTE: There are at least two more ways to update a non-topmost patch. |
760a7cfc | 173 | One is to use linkstg:refresh[] with the +$$--patch$$+ flag, the other |
ce0a1f86 | 174 | to create a new patch for the update and then merge it into the other |
760a7cfc | 175 | patch with linkstg:squash[]. |
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. | |
760a7cfc | 184 | linkstg:new[] asks you for a commit message when you create a new |
ce0a1f86 KH |
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 | ||
760a7cfc KH |
191 | In addition to linkstg:edit[], you can also give the +$$--edit$$+ flag |
192 | to linkstg:refresh[] -- that way, you get to change the commit message | |
ce0a1f86 KH |
193 | and update the patch at the same time. Use whichever feels most |
194 | natural to you. | |
195 | ||
760a7cfc | 196 | NOTE: linkstg:edit[] has a +$$--diff$$+ flag, which gives you the diff |
ce0a1f86 KH |
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. | |
760a7cfc | 204 | linkstg: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 | |
760a7cfc | 258 | at the situation with linkstg:status[]: |
ce0a1f86 KH |
259 | |
260 | $ stg status | |
ce0a1f86 KH |
261 | C TODO |
262 | ||
760a7cfc | 263 | As we were told by linkstg:push[], the conflict is in the file +TODO+. |
ce0a1f86 KH |
264 | (If the patch was bigger and touched multiple files, they would all be |
265 | listed here; prefixed with +C+ if they had conflicts, and +M+ if StGit | |
266 | managed to automatically resolve everything in the file.) | |
267 | ||
ce0a1f86 KH |
268 | At this point, we have two options: |
269 | ||
760a7cfc | 270 | 1. Undo the failed merge with linkstg:undo[]. (Remember to use the |
ce0a1f86 KH |
271 | +$$--hard$$+ flag, since the unresolved conflict means the |
272 | worktree is not clean.) | |
273 | ||
814d59e3 CM |
274 | 2. Manually resolve the conflict (editing the file directly followed |
275 | by +git add+ or using +git mergetool+.) | |
ce0a1f86 KH |
276 | |
277 | To resolve the conflict, open +TODO+ in your favorite editor. It ends | |
278 | like this: | |
279 | ||
280 | ---------------------------------------------------------------------- | |
281 | - numeric shortcuts for naming patches near top (eg. +1, -2) | |
282 | - (config?) parameter for number of patches included by "series -s" | |
283 | <<<<<<< current:TODO | |
284 | - Do something else | |
285 | ======= | |
286 | - Do something | |
287 | >>>>>>> patched:TODO | |
288 | ---------------------------------------------------------------------- | |
289 | ||
290 | The 'conflict markers' +<<<<<<<+, +=======+, and +>>>>>>>+ indicate | |
291 | which lines were already there (+current+) and which were added by the | |
292 | patch (+patched+). Edit the file so that it looks like it should; in | |
293 | this case, we want something like this: | |
294 | ||
295 | ---------------------------------------------------------------------- | |
296 | - numeric shortcuts for naming patches near top (eg. +1, -2) | |
297 | - (config?) parameter for number of patches included by "series -s" | |
298 | - Do something | |
299 | - Do something else | |
300 | ---------------------------------------------------------------------- | |
301 | ||
302 | Note that ``looks like it should'' includes removing the conflict | |
303 | markers. | |
304 | ||
305 | Now that we've resolved the conflict, we just need to tell StGit about | |
306 | it: | |
307 | ||
9ab06b98 | 308 | $ git add TODO |
ce0a1f86 KH |
309 | $ stg status |
310 | M TODO | |
311 | ||
312 | +TODO+ is listed as being modified, not in conflict. And we know from | |
313 | before how to deal with modified files: | |
314 | ||
315 | $ stg refresh | |
316 | ||
317 | The conflict is now resolved. We can see that +first+ now looks a | |
318 | little different; it no longer adds a line at the end of the file: | |
319 | ||
320 | $ stg show | |
321 | commit 8e3ae5f6fa6e9a5f831353524da5e0b91727338e | |
322 | Author: Audrey U. Thor <author@example.com> | |
323 | Date: Sun Oct 5 14:43:42 2008 +0200 | |
324 | ||
325 | First patch | |
326 | ||
327 | diff --git a/TODO b/TODO | |
328 | index 812d236..4ef3841 100644 | |
329 | --- a/TODO | |
330 | +++ b/TODO | |
331 | @@ -24,4 +24,5 @@ The future, when time allows or if someone else does them: | |
332 | they have scripts for moving the changes in one to the others) | |
333 | - numeric shortcuts for naming patches near top (eg. +1, -2) | |
334 | - (config?) parameter for number of patches included by "series -s" | |
335 | +- Do something | |
336 | - Do something else | |
337 | ||
338 | ||
339 | Workflow: Development branch | |
340 | ============================ | |
341 | ||
342 | One common use of StGit is to ``polish'' a Git branch before you | |
343 | publish it for others to see. Such history falsification can often be | |
344 | a 'good' thing -- when you (or someone else) needs to look at what you | |
345 | did six months later, you are not really interested in all the false | |
346 | starts and the steps needed to corect them. What you want is the final | |
347 | solution, presented in a way that makes it easy to read and | |
348 | understand. | |
349 | ||
350 | Of course, there are limits. Editing the last few days' worth of | |
351 | history is probably a good idea; editing the last few months' probably | |
352 | isn't. A rule of thumb might be to not mess with history old enough | |
353 | that you don't remember the details anymore. And rewriting history | |
354 | that you have published for others to see (and base their own work on) | |
355 | usually just makes everyone more confused, not less. | |
356 | ||
357 | So, let's take a concrete example. Say that you're hacking on StGit, | |
358 | and have made several Git commits as your work progressed, with commit | |
359 | messages such as ``Improve the snarfle cache'', ``Remove debug | |
360 | printout'', ``New snarfle cache test'', ``Oops, spell function name | |
361 | correctly'', ``Fix documentation error'', and ``More snarfle cache''. | |
362 | ||
363 | Now, this is the actual history, but for obvious reasons, this isn't | |
364 | the kind of history you'd ideally want to find when you six months | |
365 | from now try to figure out exactly where that elusive snarfle cache | |
366 | bug was introduced. So let's turn this into the history we can be | |
367 | proud of. The first step is to make StGit patches out of all those Git | |
368 | commits: | |
369 | ||
370 | $ stg uncommit --number 6 | |
371 | Uncommitting 6 patches ... | |
372 | Now at patch "more-snarfle-cache" | |
373 | done | |
374 | $ stg series --description | |
375 | + improve-the-snarfle-cache # Improve the snarfle cache | |
376 | + remove-debug-printout # Remove debug printout | |
377 | + new-snarfle-cache-test # New snarfle cache test | |
378 | + oops-spell-function-name-corre # Oops, spell function name correctly | |
379 | + fix-documentation-error # Fix documentation error | |
380 | > more-snarfle-cache # More snarfle cache | |
381 | ||
760a7cfc | 382 | As you can see, linkstg:uncommit[] adds StGit metadata to the last few |
ce0a1f86 KH |
383 | Git commits, turning them into StGit patches so that we can do stuff |
384 | with them. | |
385 | ||
760a7cfc | 386 | NOTE: With the +$$--number$$+ flag, linkstg:uncommit[] uncommits that |
ce0a1f86 KH |
387 | many commits and generates names for them based on their commit |
388 | messages. If you like, you can instead list the patch names you want | |
389 | on the command line. | |
390 | ||
391 | At this point, there are a number of things we could do: | |
392 | ||
760a7cfc | 393 | * Continue developing, and take advantage of e.g. linkstg:goto[] or |
ce0a1f86 KH |
394 | +stg refresh $$--patch$$+ to stick updates in the right patch to |
395 | begin with. | |
396 | ||
760a7cfc KH |
397 | * Use e.g. linkstg:float[], linkstg:sink[], linkstg:push[], and |
398 | linkstg:pop[] to reorder patches. | |
ce0a1f86 | 399 | |
760a7cfc KH |
400 | * Use linkstg:squash[] to merge two or more patches into one. |
401 | linkstgsub:squash[] pushes and pops so that the patches to be | |
ce0a1f86 KH |
402 | merged are consecutive and unrelated patches aren't in the way, |
403 | then makes one big patch out of the patches to be merged, and | |
404 | finally pushes the other patches back. | |
405 | + | |
406 | Of course, as always when there is pushing involved, there is the | |
407 | possibility of conflicts. If a push results in a conflict, the | |
408 | operation will be halted, and we'll be given the option of either | |
409 | resolving the conflict or undoing. | |
410 | ||
411 | Once we feel that the history is as good as it's going to get, we can | |
412 | remove the StGit metadata, turning the patches back into regular Git | |
413 | commits again: | |
414 | ||
415 | $ stg commit --all | |
416 | ||
760a7cfc | 417 | TIP: linkstg:commit[] can also commit specific patches (named on the |
ce0a1f86 KH |
418 | command line), leaving the rest alone. This can be used to retire |
419 | patches as they mature, while keeping the newer and more volatile | |
420 | patches as patches. | |
421 | ||
422 | ||
423 | Workflow: Tracking branch | |
424 | ========================= | |
425 | ||
e1bec2d5 KH |
426 | In the 'Development branch' workflow described above, we didn't have |
427 | to worry about other people; we're working on our branch, they are | |
428 | presumably working on theirs, and when the time comes and we're ready | |
429 | to publish our branch, we'll probably end up merging our branch with | |
430 | those other peoples'. That's how Git is designed to work. | |
ce0a1f86 | 431 | |
e1bec2d5 KH |
432 | Or rather, one of the ways Git is designed to work. An alternative, |
433 | popular in e.g. the Linux kernel community (for which Git was | |
434 | originally created), is that contributors send their patches by e-mail | |
435 | to a mailing list. Others read the patches, try them out, and provide | |
436 | feedback; often, the patch author is asked to send a new and improved | |
437 | version of the patches. Once the project maintainer is satisfied that | |
438 | the patches are good, she'll 'apply' them to a branch and publish it. | |
ce0a1f86 | 439 | |
e1bec2d5 KH |
440 | StGit is ideally suited for the process of creating patches, mailing |
441 | them out for review, revising them, mailing them off again, and | |
442 | eventually getting them accepted. | |
ce0a1f86 KH |
443 | |
444 | ||
445 | Getting patches upstream | |
446 | ------------------------ | |
447 | ||
e1bec2d5 KH |
448 | We've already covered how to clone a Git repository and start writing |
449 | patches. As for the next step, there are two commands you might use to | |
760a7cfc KH |
450 | get patches out of StGit: linkstg:mail[] and linkstg:export[]. |
451 | linkstg:export[] will export your patches to a filesystem directory as | |
e1bec2d5 KH |
452 | one text file per patch, which can be useful if you are going to send |
453 | the patches by something other than e-mail. Most of the time, though, | |
760a7cfc | 454 | linkstg:mail[] is what you want. |
e1bec2d5 KH |
455 | |
456 | NOTE: Git comes with tools for sending commits via e-mail. Since StGit | |
457 | patches are Git commits, you can use the Git tools if you like them | |
458 | better for some reason. | |
459 | ||
460 | NOTE: For exporting single patches -- as opposed to a whole bunch of | |
760a7cfc | 461 | them -- you could also use linkstg:show[] or linkstg:diff[]. |
e1bec2d5 KH |
462 | |
463 | Mailing a patch is as easy as this: | |
464 | ||
465 | $ stg mail --to recipient@example.com <patches> | |
466 | ||
467 | You can list one or more patches, or ranges of patches. Each patch | |
468 | will be sent as a separate mail, with the first line of the commit | |
469 | message as subject line. Try mailing patches to yourself to see what | |
470 | the result looks like. | |
471 | ||
760a7cfc | 472 | NOTE: linkstg:mail[] uses +sendmail+ on your computer to send the |
e1bec2d5 KH |
473 | mails. If you don't have +sendmail+ properly set up, you can instruct |
474 | it to use any SMTP server with the +$$--smtp-server$$+ flag. | |
475 | ||
476 | There are many command-line options to control exactly how mails are | |
477 | sent, as well as a message template you can modify if you want. The | |
478 | man page has all the details; I'll just mention two more here. | |
479 | ||
480 | +$$--edit-cover$$+ will open an editor and let you write an | |
481 | introductory message; all the patch mails will then be sent as replies | |
482 | to this 'cover message'. This is usually a good idea if you send more | |
483 | than one patch, so that reviewers can get a quick overview of the | |
484 | patches you sent. | |
485 | ||
486 | +$$--edit-patches$$+ will let you edit each patch before it is sent. | |
487 | You can change anything, but note that you are only editing the | |
488 | outgoing mail, not the patch itself; if you want to make changes to | |
489 | the patch, you probably want to use the regular StGit commands to do | |
490 | so. What this 'is' useful for, though, is to add notes for the patch | |
491 | recipients: | |
492 | ||
493 | ---------------------------------------------------------------------- | |
494 | From: Audrey U. Thor <author@example.com> | |
495 | Subject: [PATCH] First line of the commit message | |
496 | ||
497 | The rest of the commit message | |
498 | ||
499 | --- | |
500 | ||
501 | Everything after the line with the three dashes and before the diff is | |
502 | just a comment, and not part of the commit message. If there's | |
503 | anything you want the patch recipients to see, but that shouldn't be | |
504 | recorded in the history if the patch is accepted, write it here. | |
505 | ||
506 | stgit/main.py | 1 + | |
507 | 1 files changed, 1 insertions(+), 0 deletions(-) | |
508 | ||
509 | ||
510 | diff --git a/stgit/main.py b/stgit/main.py | |
511 | index e324179..6398958 100644 | |
512 | --- a/stgit/main.py | |
513 | +++ b/stgit/main.py | |
514 | @@ -171,6 +171,7 @@ def _main(): | |
515 | sys.exit(ret or utils.STGIT_SUCCESS) | |
516 | ||
517 | def main(): | |
518 | + print 'My first patch!' | |
519 | try: | |
520 | _main() | |
521 | finally: | |
522 | ---------------------------------------------------------------------- | |
523 | ||
524 | ||
525 | Rebasing a patch series | |
526 | ----------------------- | |
527 | ||
2b5462d7 KH |
528 | While you are busy writing, submitting, and revising your patch |
529 | series, other people will be doing the same thing. As a result, even | |
530 | though you started writing your patches on top of what was the latest | |
531 | history at the time, your stack base will grow ever more out of date. | |
532 | ||
533 | When you clone a repository, | |
534 | ||
535 | $ stg clone http://homepage.ntlworld.com/cmarinas/stgit.git stgit | |
536 | ||
537 | you initially get one local branch, +master+. You also get a number of | |
538 | 'remote' branches, one for each branch in the repository you cloned. | |
539 | In the case of the StGit repository, these are | |
540 | +remotes/origin/stable+, +remotes/origin/master+, and | |
541 | +remotes/origin/proposed+. +remotes+ means that it's not a local | |
542 | branch, just a snapshot of a branch in another repository; and | |
543 | +origin+ is the default name for the first remote repository (you can | |
544 | set up more; see the man page for +git remote+). | |
545 | ||
546 | Right after cloning, +master+ and +remotes/origin/master+ point at the | |
547 | same commit. When you start writing patches, +master+ will advance, | |
548 | and always point at the current topmost patch, but | |
549 | +remotes/origin/master+ will stay the same because it represents the | |
550 | master branch in the repository you cloned from -- your 'upstream' | |
551 | repository. | |
552 | ||
553 | Unless you are the only one working on the project, however, the | |
554 | upstream repository will not stay the same forever. New commits will | |
555 | be added to its branches; to update your clone, run | |
556 | ||
557 | $ git remote update | |
558 | ||
559 | This will update all your remote branches, but won't touch your local | |
560 | branches. To get the latest changes into your local +master+ branch, | |
760a7cfc | 561 | use linkstg:rebase[]: |
2b5462d7 KH |
562 | |
563 | $ stg rebase remotes/origin/master | |
564 | ||
565 | This command will do three things: | |
566 | ||
567 | 1. Pop all patches, so that your local branch (+master+, in this | |
568 | example) points at the stack base. This is the same commit that | |
569 | +remotes/origin/master+ pointed at at the time you started | |
570 | writing your patches. | |
571 | ||
572 | 2. Set the stack base to the given commit (the current, updated | |
573 | value of +remotes/origin/master+). | |
574 | ||
575 | 3. Push the patches that were popped in the first step. | |
576 | ||
577 | The end result is that your patches are now applied on top of the | |
578 | latest version of +remotes/origin/master+. | |
579 | ||
580 | The primary reason for rebasing is to reduce the amount of conflicts | |
581 | between your work and others'. If one of your patches changes the same | |
582 | part of the same file as a patch someone else has written, you will | |
760a7cfc | 583 | get a conflict when you run linkstg:rebase[] the next time after the |
2b5462d7 KH |
584 | other person's patch has been accepted upstream. It is almost always |
585 | less work to rebase often and resolve these one at a time, rather than | |
586 | a whole lot at once. After all, you have to rebase eventually; if you | |
587 | mail out patches that are based on an outdated branch, everyone who | |
588 | tries to apply them has to resolve the conflicts instead. There are | |
589 | more effective ways to get popular. | |
590 | ||
591 | ||
592 | When your patches are accepted | |
593 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
594 | ||
595 | If and when some or all of your patches are accepted upstream, you | |
596 | update and rebase just like usual -- but be sure to use the | |
760a7cfc | 597 | +$$--merged$$+ flag to linkstg:rebase[]: |
2b5462d7 KH |
598 | |
599 | $ git remote update | |
600 | $ stg rebase --merged remotes/origin/master | |
601 | ||
602 | This flag makes the rebase operation better at detecting that your | |
603 | patches have been merged, at some cost in performance. | |
604 | ||
605 | The patches that had been merged will still be present in your patch | |
606 | stack after the rebase, but they will be empty, since the change they | |
760a7cfc | 607 | added is now already present in the stack base. Run linkstg:clean[] to |
2b5462d7 KH |
608 | get rid of such empty patches if you don't want them hanging around: |
609 | ||
610 | $ stg clean | |
c2428e5a | 611 | |
c2428e5a | 612 | |
ce0a1f86 KH |
613 | Importing patches |
614 | ----------------- | |
c2428e5a | 615 | |
fc552485 KH |
616 | While you are busy producing patches, there's hopefully someone -- the |
617 | 'maintainer' -- at the other end who recieves them and 'applies' them | |
618 | to her Git tree, which is then published for all (or parts of) the | |
619 | world to see. | |
620 | ||
621 | It's perfectly fine for this person to not have the foggiest idea what | |
622 | StGit is. In that case, she'll probably apply your patches with | |
623 | something like +git am+, and everything will just work, exactly as if | |
624 | you'd used Git to send those patches. But she might be an StGit user | |
760a7cfc | 625 | too, in which case she might use linkstg:import[]. |
fc552485 KH |
626 | |
627 | There are basically four kinds if stuff you can import with | |
760a7cfc | 628 | linkstg:import[]: |
fc552485 KH |
629 | |
630 | 1. A patch in a file. | |
631 | ||
632 | 2. Several files containing one patch each, and a 'series' file | |
633 | listing those other files in the correct order. | |
634 | ||
635 | 3. An e-mail containing a single patch. | |
636 | ||
637 | 4. A mailbox file (in standard Unix +mbox+ format) containing | |
638 | multiple e-mails with one patch in each. | |
639 | ||
640 | ||
641 | Importing a plain patch | |
642 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
643 | ||
644 | Importing a plain patch, such as produced by e.g. GNU +diff+, +git | |
760a7cfc | 645 | diff+, +git show+, linkstg:diff[], or linkstg:show[], is very easy. |
fc552485 KH |
646 | Just say |
647 | ||
648 | $ stg import my-patch | |
649 | ||
650 | and you'll have a new patch at the top of your stack. | |
651 | ||
760a7cfc | 652 | If you don't give a file name on the command line, linkstg:import[] |
fc552485 KH |
653 | will read the patch from its standard input -- in other words, you can |
654 | pipe a patch to it directly from the command that produces it. | |
655 | ||
656 | By default, the new patch's name will be taken from the file name, and | |
657 | its commit message and author info will be taken from the beginning of | |
658 | the patch, if they are there. However, there are command line switches | |
659 | to override all of these things; see the man page for details. | |
660 | ||
661 | ||
662 | Importing several patches at once | |
663 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
664 | ||
760a7cfc | 665 | Some programs -- among them linkstg:export[] -- will create a bunch of |
fc552485 KH |
666 | files with one patch in each, and a 'series' file (often called |
667 | +series+) listing the other files in the correct order. Give | |
760a7cfc | 668 | +$$--series$$+ and the name of the series file to linkstg:import[], |
fc552485 KH |
669 | and it will import all the patches for you, in the correct order. |
670 | ||
671 | ||
672 | Importing a patch from an e-mail | |
673 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
674 | ||
675 | Importing a patch from an e-mail is simple too: | |
676 | ||
677 | $ stg import --mail my-mail | |
678 | ||
679 | The e-mail should be in standard Git mail format (which is what e.g. | |
760a7cfc | 680 | linkstg:mail[] produces) -- that is, with the patch in-line in the |
fc552485 KH |
681 | mail, not attached. The authorship info is taken from the mail |
682 | headers, and the commit message is read from the 'Subject:' line and | |
683 | the mail body. | |
684 | ||
685 | If you don't give a file name, the mail will be read from the standard | |
686 | input. This means that, if your mail reader supports it, you can pipe | |
687 | a mail directly to +stg import $$--mail$$+ and the patch will be | |
688 | applied. | |
689 | ||
690 | ||
691 | Importing a mailbox full of patches | |
692 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
693 | ||
694 | Finally, in case importing one patch at a time is too much work, | |
760a7cfc | 695 | linkstg:import[] also accepts an entire Unix +mbox+-format mailbox, |
fc552485 KH |
696 | either on the command line or on its standard input; just use the |
697 | +$$--mbox$$+ flag. Each mail should contain one patch, and is imported | |
698 | just like with +$$--mail$$+. | |
699 | ||
760a7cfc | 700 | Mailboxes full of patches are produced by e.g. linkstg:mail[] with the |
fc552485 KH |
701 | +$$--mbox$$+ flag, but most mail readers can produce them too, meaning |
702 | that you can copy all the patch mails you want to apply to a separate | |
703 | mailbox, and then import them all in one go. | |
c2428e5a | 704 | |
c2428e5a | 705 | |
ce0a1f86 KH |
706 | Other stuff that needs to be placed somewhere |
707 | ============================================= | |
708 | ||
709 | ||
710 | Undo | |
711 | ---- | |
d1c8fcd7 | 712 | |
ce0a1f86 | 713 | TODO:: undo, redo, log, reset |
d1c8fcd7 | 714 | |
d1c8fcd7 | 715 | |
ce0a1f86 KH |
716 | Interoperating with Git |
717 | ----------------------- | |
d1c8fcd7 | 718 | |
ce0a1f86 | 719 | TODO:: |
d1c8fcd7 | 720 | |
ce0a1f86 | 721 | * git commit + repair |
d1c8fcd7 | 722 | |
ce0a1f86 | 723 | * git reset HEAD~n + repair |
d1c8fcd7 | 724 | |
ce0a1f86 | 725 | * don't do git rebase or git merge, because it won't work |
d1c8fcd7 | 726 | |
d1c8fcd7 | 727 | |
ce0a1f86 KH |
728 | Patch stuff |
729 | ----------- | |
d1c8fcd7 | 730 | |
ce0a1f86 KH |
731 | TODO:: This section needs revising. I've only fixed the formatting. |
732 | Most of it should go under "Workflow: Tracking branch" | |
733 | ||
734 | As mentioned in the introduction, StGit stores modifications to your | |
735 | working tree in the form of Git commits. This means if you want to | |
736 | apply your changes to a tree not managed by Git, or send your changes | |
737 | to someone else in e-mail, you need to convert your StGit patches into | |
738 | normal textual diffs that can be applied with the GNU patch command. | |
760a7cfc | 739 | linkstg:diff[] is a powerful way to generate and view textual diffs of |
ce0a1f86 | 740 | patches managed by StGit. |
d1c8fcd7 | 741 | |
c2428e5a | 742 | To view a diff of the topmost patch: |
d1c8fcd7 | 743 | |
ce0a1f86 | 744 | $ stg diff -r / |
d1c8fcd7 | 745 | |
c2428e5a | 746 | Observe that this does not show any changes in the working directory |
760a7cfc | 747 | that have not been saved by a linkstgsub:refresh[]. To view just the |
ce0a1f86 | 748 | changes you've made since the last refresh, use: |
d1c8fcd7 | 749 | |
ce0a1f86 | 750 | $ stg diff -r /top |
d1c8fcd7 | 751 | |
c2428e5a CM |
752 | If you want to see the changes made by the patch combined with any |
753 | unsaved changes in the working directory, try: | |
d1c8fcd7 | 754 | |
ce0a1f86 | 755 | $ stg diff -r /bottom |
d1c8fcd7 | 756 | |
c2428e5a | 757 | You can also show the changes to any patch in your stack with: |
d1c8fcd7 | 758 | |
ce0a1f86 | 759 | $ stg diff -r <patch>/ |
d1c8fcd7 | 760 | |
c2428e5a CM |
761 | Use this command to view all the changes in your stack up through the |
762 | current patch: | |
763 | ||
ce0a1f86 | 764 | $ stg diff -r base |
d1c8fcd7 | 765 | |
760a7cfc | 766 | linkstg:diff[] supports a number of other features that are very |
ce0a1f86 KH |
767 | useful. Be sure to take a look at the help information for this |
768 | command. To convert your StGit patches into patch files: | |
d1c8fcd7 | 769 | |
ce0a1f86 | 770 | $ stg export [--range=[<patch1>[:<patch2>]]] [<dir-name>] |
d1c8fcd7 | 771 | |
760a7cfc | 772 | linkstg:export[] supports options to automatically number the patches |
ce0a1f86 | 773 | (+-n+) or add the +.diff+ extension (+-d+). If you don't tell |
760a7cfc | 774 | linkstgsub:export[] where to put the patches, it will create directory |
ce0a1f86 KH |
775 | named +patch-<branchname>+ in your current directory, and store the |
776 | patches there. To e-mail a patch or range of patches: | |
c2428e5a | 777 | |
ce0a1f86 | 778 | $ stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>) |
c2428e5a | 779 | |
760a7cfc | 780 | linkstg:mail[] has a lot of options, so read the output of +stg mail |
ce0a1f86 | 781 | -h+ for more information. |
c2428e5a | 782 | |
ce0a1f86 | 783 | You can also import an existing GNU diff patch file as a new StGit |
760a7cfc | 784 | patch with a single command. linkstg:import[] will automatically parse |
ce0a1f86 | 785 | through the patch file and extract a patch description. Use: |
d1c8fcd7 | 786 | |
ce0a1f86 | 787 | $ stg import [<file>] |
d1c8fcd7 | 788 | |
ce0a1f86 | 789 | This is the equivalent of |
d1c8fcd7 | 790 | |
ce0a1f86 KH |
791 | $ stg new |
792 | $ patch -i <file> | |
793 | $ stg refresh -e | |
d1c8fcd7 | 794 | |
ce0a1f86 | 795 | Sometimes the patch file won't apply cleanly. In that case, |
760a7cfc | 796 | linkstg:import[] will leave you with an empty StGit patch, to which |
ce0a1f86 KH |
797 | you then apply the patch file by hand using "patch -i" and your |
798 | favorite editor. | |
d1c8fcd7 | 799 | |
ce0a1f86 KH |
800 | To merge a GNU diff file (defaulting to the standard input) into the |
801 | topmost patch: | |
d1c8fcd7 | 802 | |
ce0a1f86 | 803 | $ stg fold [<file>] |
c2428e5a | 804 | |
ce0a1f86 KH |
805 | This command supports a +$$--threeway$$+ option which applies the |
806 | patch onto the bottom of the topmost one and performs a three-way | |
807 | merge. | |
27373fe0 | 808 | |
c2428e5a | 809 | |
27373fe0 CM |
810 | Templates |
811 | --------- | |
d1c8fcd7 | 812 | |
ce0a1f86 KH |
813 | TODO:: This section needs revising. I've only fixed the formatting. |
814 | ||
760a7cfc | 815 | linkstg:export[] and linkstg:mail[] use templates for generating the |
ce0a1f86 KH |
816 | patch files or e-mails. The default templates are installed under |
817 | +<prefix>/share/stgit/templates/+ and, combined with the extra options | |
818 | available for these commands, should be enough for most users. The | |
819 | template format uses the standard Python string formatting rules. The | |
820 | variables available are listed in the the manual pages for each | |
760a7cfc | 821 | command. linkstg:mail[] can also send an initial 'cover' e-mail for |
ce0a1f86 KH |
822 | which there is no default template. The |
823 | +<prefix>/share/stgit/examples/firstmail.tmpl+ file can be used as an | |
824 | example. A default description for new patches can be defined in the | |
825 | +.git/ patchdescr.tmpl+ file. This is useful for things like | |
826 | signed-off-by lines. | |
1d694f9b GH |
827 | |
828 | Emacs | |
829 | ===== | |
830 | ||
831 | StGit comes with an Emacs mode, +stgit-mode+, supporting Emacs | |
832 | versions 22 and later. | |
833 | ||
834 | To start using it, add the +stgit/contrib+ directory to your Emacs | |
835 | load-path and run +(require 'stgit)+. For example, you can add the | |
836 | following to your +.emacs+ file: | |
837 | ||
838 | ---------------------------------------------------------------------- | |
839 | (add-to-list 'load-path "/path/to/stgit/contrib") | |
840 | (require 'stgit) | |
841 | ---------------------------------------------------------------------- | |
842 | ||
843 | Start +stgit-mode+ using +M-x stgit+ and select the directory where | |
844 | the source code you want to use StGit on can be found. If StGit has | |
845 | not been initialized in this directory yet, you will need to run +M-x | |
846 | stgit-init+ before you continue. | |
847 | ||
848 | The +stgit-mode+ buffer (usually named +$$*stgit*$$+) has the | |
849 | following layout: | |
850 | ||
851 | ---------------------------------------------------------------------- | |
852 | Branch: name-of-branch | |
853 | ||
854 | + The first applied patch | |
855 | + Another applied patch | |
856 | > The topmost patch | |
857 | Index | |
858 | <no files> | |
859 | Work Tree | |
860 | <no files> | |
861 | - An unapplied patch | |
862 | - Another unapplied patch | |
863 | -- | |
864 | ---------------------------------------------------------------------- | |
865 | ||
866 | The above means that the active branch name is +name-of-branch+ and it | |
867 | contains five patches, three of which are applied. The git index and | |
868 | working tree contain no (modified) files. | |
869 | ||
870 | Basic Commands | |
871 | -------------- | |
872 | ||
873 | To get help, press +h+. This opens a new buffer which lists all | |
874 | commands supported in +stgit-mode+. Also, if you have the menu bar | |
875 | enabled (toggled using +M-x menu-bar-mode+), a new menu entry called | |
876 | +StGit+ will appear, from which you can run several StGit commands. As | |
877 | the menu should be self-explanatory, the rest of this tutorial will | |
878 | focus on available keyboard commands. | |
879 | ||
880 | Move the point (cursor) between lines using +C-p+ and +C-n+, or | |
881 | between patches using +p+ and +n+. | |
882 | ||
883 | You can linkstgsub:undo[] and linkstgsub:redo[] StGit commands using | |
884 | +C-/+ and +C-c C-/+, respectively. | |
885 | ||
886 | Creating New Patches | |
887 | -------------------- | |
888 | ||
889 | If you want to create a new patch, first make some changes that should | |
890 | go into it. As you save a file which is Git-controlled, it will appear | |
891 | as a modification in the +Work Tree+ section: | |
892 | ||
893 | ---------------------------------------------------------------------- | |
894 | Work Tree | |
895 | Modified foo.txt | |
896 | ---------------------------------------------------------------------- | |
897 | ||
898 | To create a new patch based on the changes in the index or, if it | |
899 | contains no changes, the working tree, press +c+. This opens a new | |
900 | buffer where you can enter the patch description. When you are done, | |
901 | press +C-c C-c+. Your new patch will now show up in the +$$*stgit*$$+ | |
902 | buffer, and the working tree will no longer contain any modifications: | |
903 | ||
904 | ---------------------------------------------------------------------- | |
905 | + The topmost patch | |
906 | > First line of your new description | |
907 | Index | |
908 | <no files> | |
909 | Work Tree | |
910 | <no files> | |
911 | ---------------------------------------------------------------------- | |
912 | ||
913 | As you make additional changes in your files, and want to include them | |
914 | in the topmost patch, press +r+, which runs linkstg:refresh[]. If you | |
915 | want to add the changes to a patch which is not topmost, move the | |
916 | point to the line of that patch and press +C-u r+. | |
917 | ||
918 | Inspecting Patches | |
919 | ------------------ | |
920 | ||
921 | To see what a particular patch contains, you can move the point | |
922 | (cursor) to the line of that patch, and press +RET+ (Enter). This will | |
923 | "expand" the patch and show which files it changes: | |
924 | ||
925 | ---------------------------------------------------------------------- | |
926 | + My patch | |
927 | Modified foo.txt | |
928 | Deleted bar.c | |
929 | ---------------------------------------------------------------------- | |
930 | ||
931 | You can press +=+, which will show the diff of that patch or file in a | |
932 | new buffer. With a prefix argument (+C-u =+), the diff will not show | |
933 | changes in whitespace. | |
934 | ||
935 | To visit (open) a modified file in another Emacs window, press +o+ on | |
936 | that line. +RET+ will visit it in the current window. | |
937 | ||
938 | Changing the Patch Series | |
939 | ------------------------- | |
940 | ||
941 | You can linkstgsub:push[] and linkstgsub:pop[] patches using +>+ | |
942 | (pushes the topmost unapplied patch onto the stack) and +<+ (pops the | |
943 | topmost applied patch off the stack). | |
944 | ||
945 | By moving the point to a particular patch and pressing +P+ (+S-p+) | |
946 | you either (if it already was applied) pop that patch off the stack, | |
947 | or (if it was unapplied) push it onto the stack. | |
948 | ||
949 | You can move patches by first marking one or more using +m+. Then, | |
950 | move the point to where in the series you want these patches to move, | |
951 | and press +M+. Use +DEL+ or +u+ to remove a mark. | |
952 | ||
953 | You can also combine (linkstgsub:squash[]) two or more patches by | |
954 | marking them and pressing +S+ (+S-s+). This will open a new buffer | |
955 | where you can edit the patch description of the new, combined, patch. | |
956 | When done, press +C-c C-c+, and the topmost of the marked patches will | |
957 | be replaced in the stack by one combined patch. | |
958 | ||
959 | You can linkstgsub:delete[] a patch by moving to its line and pressing | |
960 | +D+. If you press +C-u D+, the contents of the patch will be spilled | |
961 | to the index. | |
962 | ||
963 | To linkstgsub:edit[] the description of a patch, press +e+. This opens | |
964 | the patch description in a new buffer. Press +C-c C-c+ when you are | |
965 | done editing the patch. | |
966 | ||
967 | These operations may result in merge conflicts; more about that later. | |
968 | ||
969 | Patch Names | |
970 | ----------- | |
971 | ||
972 | By default, the patch description is shown but not the patch names. | |
973 | You can toggle showing the names using +t n+. To rename a patch, press | |
974 | +C-c C-r+. | |
975 | ||
bf7e391c GH |
976 | Showing Committed Patches |
977 | ------------------------- | |
978 | ||
979 | Sometimes it is convenient to be able to investigate already committed | |
980 | patches. Toggle showing these using +t h+. With a prefix argument, you | |
981 | can set how many to show; e.g., +M-7 t h+ will show seven already | |
982 | committed patches. | |
983 | ||
1d694f9b GH |
984 | Using the Index and Working Tree |
985 | -------------------------------- | |
986 | ||
987 | You can move a changed file between the index and the working tree | |
988 | using +i+. This is useful if your working tree contains a number of | |
989 | changes and you want to create or refresh a patch using only some of | |
990 | the changed file. Once you have the correct set of files in the index, | |
991 | use +c+ to create or +r+ to refresh patches using only the files in | |
992 | the index. | |
993 | ||
994 | If you want to revert a change in either the index or the working | |
995 | tree, move the point to that line and press +U+. If you press +U+ on | |
996 | the +Index+ or +Work Tree+ lines, all the changes in the index or | |
997 | working tree will be reverted. | |
998 | ||
999 | Branches | |
1000 | -------- | |
1001 | ||
1002 | You can switch to another linkstgsub:branch[] by pressing +B+. If you | |
1003 | type the name of a branch that does not exist, you will be asked | |
1004 | whether to create one. The new branch will be based off the current | |
1005 | +HEAD+. | |
1006 | ||
1007 | Use +C-c C-b+ to linkstgsub:rebase[] the current branch. It will | |
1008 | default to rebasing to the +git config+ setting for | |
1009 | +branch._branch_.stgit.parentbranch+. | |
1010 | ||
1011 | Merge Conflicts | |
1012 | --------------- | |
1013 | ||
1014 | If an operation resulted in a merge conflict, the files with conflicts | |
1015 | will show as +Unmerged+ in the +$$*stgit*$$+ buffer. | |
1016 | ||
1017 | To handle the conflicts, you can linkstgsub:undo[] the operation that | |
1018 | caused the conflict using +C-u C-/+. Note the +C-u+ prefix, which will | |
1019 | tell the undo operation to continue despite the index or working tree | |
1020 | containing changes. | |
1021 | ||
1022 | If you instead want to resovle the changes, you must first edit the | |
1023 | files with conflicts to make sure they are in the correct state. Once | |
1024 | you have done this, press +R+ on the line of that file, which will | |
1025 | remove the +Unmerged+ flag. Once all conflicts have been resolved, you | |
1026 | can continue working as normal, for example by refreshing the patch | |
1027 | that had the conflict. | |
1028 | ||
1029 | To investigate the reason of conflicts, you can use the +d b+, +d o+, | |
1030 | and +d t+ commands to, respectively, show the diffs against the merge | |
1031 | base, our branch, or their branch. +d c+ shows a combined diff. See | |
1032 | linkman:git-diff[1] for more information about these commands. | |
1033 | ||
1034 | A more powerful tool to resolve conflicts is the Emacs +smerge-mode+. | |
1035 | To start using it to resolve a conflict, press +d m+. It is outside | |
1036 | the scope of this tutorial to explain how to use it, but press +q+ to | |
1037 | leave +smerge-mode+. |