| 1 | StGit tutorial |
| 2 | ############## |
| 3 | |
| 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. |
| 10 | |
| 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]. |
| 15 | |
| 16 | |
| 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 |
| 37 | =============== |
| 38 | |
| 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 |
| 45 | |
| 46 | Before you can create StGit patches, you have to run linkstg:init[]: |
| 47 | |
| 48 | $ stg init |
| 49 | |
| 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.) |
| 53 | |
| 54 | NOTE: As a shortcut, linkstg:clone[] will run +git clone+ followed by |
| 55 | +stg init+ for you. |
| 56 | |
| 57 | |
| 58 | Creating a patch |
| 59 | ---------------- |
| 60 | |
| 61 | Now we're ready to create our first patch: |
| 62 | |
| 63 | $ stg new my-first-patch |
| 64 | |
| 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 linkstg:show[] will tell |
| 69 | you: |
| 70 | |
| 71 | $ stg show |
| 72 | |
| 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: |
| 76 | |
| 77 | $ stg status |
| 78 | M stgit/main.py |
| 79 | |
| 80 | Then linkstgsub:refresh[] the patch: |
| 81 | |
| 82 | $ stg refresh |
| 83 | |
| 84 | And voilĂ -- the patch is no longer empty: |
| 85 | |
| 86 | $ stg show |
| 87 | commit 3de32068c600d40d8af2a9cf1f1c762570ae9610 |
| 88 | Author: Audrey U. Thor <author@example.com> |
| 89 | Date: Sat Oct 4 16:10:54 2008 +0200 |
| 90 | |
| 91 | Tell the world that I've made a patch |
| 92 | |
| 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) |
| 99 | |
| 100 | def main(): |
| 101 | + print 'My first patch!' |
| 102 | try: |
| 103 | _main() |
| 104 | finally: |
| 105 | |
| 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.) |
| 111 | |
| 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[]. |
| 114 | |
| 115 | Creating another patch |
| 116 | ---------------------- |
| 117 | |
| 118 | We want to make another improvement, so let's create a new patch for |
| 119 | it: |
| 120 | |
| 121 | $ echo 'Audrey U. Thor' > AUTHORS |
| 122 | $ stg new credit --message 'Give me some credit' |
| 123 | $ stg refresh |
| 124 | |
| 125 | Note that we can give the commit message on the command line, and that |
| 126 | it doesn't matter whether we run linkstg:new[] before or after we edit |
| 127 | the files. |
| 128 | |
| 129 | So now we have two patches: |
| 130 | |
| 131 | $ stg series --description |
| 132 | + my-first-patch # This is my first patch |
| 133 | > credit # Give me some credit |
| 134 | |
| 135 | linkstg: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. |
| 138 | |
| 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 linkstgsub:pop[] the +credit+ |
| 142 | patch, so that +my-first-patch+ becomes topmost again: |
| 143 | |
| 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 |
| 151 | |
| 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 |
| 154 | make. |
| 155 | |
| 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 linkstg:push[] command away from being |
| 161 | restored: |
| 162 | |
| 163 | $ stg push credit |
| 164 | Checking for changes in the working directory ... done |
| 165 | Fast-forwarded patch "credit" |
| 166 | Now at patch "credit" |
| 167 | |
| 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 |
| 170 | pop the topmost patch, respectively. |
| 171 | |
| 172 | NOTE: There are at least two more ways to update a non-topmost patch. |
| 173 | One is to use linkstg: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 linkstg:squash[]. |
| 176 | |
| 177 | |
| 178 | Keeping commit messages up to date |
| 179 | ---------------------------------- |
| 180 | |
| 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 | linkstg: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 linkstg:edit[], you can also give the +$$--edit$$+ flag |
| 192 | to linkstg: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: linkstg: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 | linkstg:rename[] is your friend there. |
| 205 | |
| 206 | |
| 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 linkstg:status[]: |
| 259 | |
| 260 | $ stg status |
| 261 | ? TODO.ancestor |
| 262 | ? TODO.current |
| 263 | ? TODO.patched |
| 264 | C TODO |
| 265 | |
| 266 | As we were told by linkstg: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 linkstg: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, linkstg: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, linkstg: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. linkstg:goto[] or |
| 402 | +stg refresh $$--patch$$+ to stick updates in the right patch to |
| 403 | begin with. |
| 404 | |
| 405 | * Use e.g. linkstg:float[], linkstg:sink[], linkstg:push[], and |
| 406 | linkstg:pop[] to reorder patches. |
| 407 | |
| 408 | * Use linkstg:squash[] to merge two or more patches into one. |
| 409 | linkstgsub:squash[] 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: linkstg:commit[] can also commit specific patches (named on the |
| 426 | command line), leaving the rest alone. This can be used to retire |
| 427 | patches as they mature, while keeping the newer and more volatile |
| 428 | patches as patches. |
| 429 | |
| 430 | |
| 431 | Workflow: Tracking branch |
| 432 | ========================= |
| 433 | |
| 434 | 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. |
| 439 | |
| 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. |
| 447 | |
| 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. |
| 451 | |
| 452 | |
| 453 | Getting patches upstream |
| 454 | ------------------------ |
| 455 | |
| 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: linkstg:mail[] and linkstg:export[]. |
| 459 | linkstg: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 | linkstg: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 linkstg:show[] or linkstg: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: linkstg: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 | |
| 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 linkstg: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 linkstg: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 linkstg: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 linkstg:clean[] to |
| 616 | get rid of such empty patches if you don't want them hanging around: |
| 617 | |
| 618 | $ stg clean |
| 619 | |
| 620 | |
| 621 | Importing patches |
| 622 | ----------------- |
| 623 | |
| 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 linkstg:import[]. |
| 634 | |
| 635 | There are basically four kinds if stuff you can import with |
| 636 | linkstg: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+, linkstg:diff[], or linkstg: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, linkstg: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 linkstg: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 linkstg: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 | linkstg: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 | linkstg: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. linkstg: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. |
| 712 | |
| 713 | |
| 714 | Other stuff that needs to be placed somewhere |
| 715 | ============================================= |
| 716 | |
| 717 | |
| 718 | Undo |
| 719 | ---- |
| 720 | |
| 721 | TODO:: undo, redo, log, reset |
| 722 | |
| 723 | |
| 724 | Interoperating with Git |
| 725 | ----------------------- |
| 726 | |
| 727 | TODO:: |
| 728 | |
| 729 | * git commit + repair |
| 730 | |
| 731 | * git reset HEAD~n + repair |
| 732 | |
| 733 | * don't do git rebase or git merge, because it won't work |
| 734 | |
| 735 | |
| 736 | Patch stuff |
| 737 | ----------- |
| 738 | |
| 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 | linkstg:diff[] is a powerful way to generate and view textual diffs of |
| 748 | patches managed by StGit. |
| 749 | |
| 750 | To view a diff of the topmost patch: |
| 751 | |
| 752 | $ stg diff -r / |
| 753 | |
| 754 | Observe that this does not show any changes in the working directory |
| 755 | that have not been saved by a linkstgsub:refresh[]. To view just the |
| 756 | changes you've made since the last refresh, use: |
| 757 | |
| 758 | $ stg diff -r /top |
| 759 | |
| 760 | If you want to see the changes made by the patch combined with any |
| 761 | unsaved changes in the working directory, try: |
| 762 | |
| 763 | $ stg diff -r /bottom |
| 764 | |
| 765 | You can also show the changes to any patch in your stack with: |
| 766 | |
| 767 | $ stg diff -r <patch>/ |
| 768 | |
| 769 | Use this command to view all the changes in your stack up through the |
| 770 | current patch: |
| 771 | |
| 772 | $ stg diff -r base |
| 773 | |
| 774 | linkstg: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: |
| 777 | |
| 778 | $ stg export [--range=[<patch1>[:<patch2>]]] [<dir-name>] |
| 779 | |
| 780 | linkstg:export[] supports options to automatically number the patches |
| 781 | (+-n+) or add the +.diff+ extension (+-d+). If you don't tell |
| 782 | linkstgsub: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: |
| 785 | |
| 786 | $ stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>) |
| 787 | |
| 788 | linkstg:mail[] has a lot of options, so read the output of +stg mail |
| 789 | -h+ for more information. |
| 790 | |
| 791 | You can also import an existing GNU diff patch file as a new StGit |
| 792 | patch with a single command. linkstg:import[] will automatically parse |
| 793 | through the patch file and extract a patch description. Use: |
| 794 | |
| 795 | $ stg import [<file>] |
| 796 | |
| 797 | This is the equivalent of |
| 798 | |
| 799 | $ stg new |
| 800 | $ patch -i <file> |
| 801 | $ stg refresh -e |
| 802 | |
| 803 | Sometimes the patch file won't apply cleanly. In that case, |
| 804 | linkstg: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. |
| 807 | |
| 808 | To merge a GNU diff file (defaulting to the standard input) into the |
| 809 | topmost patch: |
| 810 | |
| 811 | $ stg fold [<file>] |
| 812 | |
| 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. |
| 816 | |
| 817 | |
| 818 | Templates |
| 819 | --------- |
| 820 | |
| 821 | TODO:: This section needs revising. I've only fixed the formatting. |
| 822 | |
| 823 | linkstg:export[] and linkstg: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. linkstg: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. |