{"thread":{"id":"16071","subject":"[StGit PATCH] Tutorial: Importing patches","startedAt":"2008-10-28T20:42:23Z","lastAt":"2008-10-29T10:28:14Z","messageCount":3,"participants":["Karl Hasselström","Catalin Marinas"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"94137","messageId":"20081028204223.9539.89315.stgit@yoghurt","threadId":"16071","inReplyTo":null,"subject":"[StGit PATCH] Tutorial: Importing patches","fromName":"Karl Hasselström","fromEmail":"kha@treskal.com","sentAt":"2008-10-28T20:42:23Z","receivedAt":"2008-10-28T20:42:23Z","isPatch":true,"sender":{"key":"kha@treskal.com","avatar":"https://gravatar.com/avatar/f0120c734b5279b345075a28521e1ac66acb20c9913ffe9bf6ae97e53f7f3f13?d=mp&s=160"},"body":"Signed-off-by: Karl Hasselström <kha@treskal.com>\n\n---\n\n Documentation/tutorial.txt |   89 ++++++++++++++++++++++++++++++++++++++++++++\n 1 files changed, 88 insertions(+), 1 deletions(-)\n\n\ndiff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt\nindex 2808462..283b358 100644\n--- a/Documentation/tutorial.txt\n+++ b/Documentation/tutorial.txt\n@@ -621,7 +621,94 @@ get rid of such empty patches if you don't want them hanging around:\n Importing patches\n -----------------\n \n-TODO:: import, ...\n+While you are busy producing patches, there's hopefully someone -- the\n+'maintainer' -- at the other end who recieves them and 'applies' them\n+to her Git tree, which is then published for all (or parts of) the\n+world to see.\n+\n+It's perfectly fine for this person to not have the foggiest idea what\n+StGit is. In that case, she'll probably apply your patches with\n+something like +git am+, and everything will just work, exactly as if\n+you'd used Git to send those patches. But she might be an StGit user\n+too, in which case she might use stglink:import[].\n+\n+There are basically four kinds if stuff you can import with\n+stglink:import[]:\n+\n+  1. A patch in a file.\n+\n+  2. Several files containing one patch each, and a 'series' file\n+     listing those other files in the correct order.\n+\n+  3. An e-mail containing a single patch.\n+\n+  4. A mailbox file (in standard Unix +mbox+ format) containing\n+     multiple e-mails with one patch in each.\n+\n+\n+Importing a plain patch\n+~~~~~~~~~~~~~~~~~~~~~~~\n+\n+Importing a plain patch, such as produced by e.g. GNU +diff+, +git\n+diff+, +git show+, stglink:diff[], or stglink:show[], is very easy.\n+Just say\n+\n+  $ stg import my-patch\n+\n+and you'll have a new patch at the top of your stack.\n+\n+If you don't give a file name on the command line, stglink:import[]\n+will read the patch from its standard input -- in other words, you can\n+pipe a patch to it directly from the command that produces it.\n+\n+By default, the new patch's name will be taken from the file name, and\n+its commit message and author info will be taken from the beginning of\n+the patch, if they are there. However, there are command line switches\n+to override all of these things; see the man page for details.\n+\n+\n+Importing several patches at once\n+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n+\n+Some programs -- among them stglink:export[] -- will create a bunch of\n+files with one patch in each, and a 'series' file (often called\n++series+) listing the other files in the correct order. Give\n++$$--series$$+ and the name of the series file to stglink:import[],\n+and it will import all the patches for you, in the correct order.\n+\n+\n+Importing a patch from an e-mail\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+Importing a patch from an e-mail is simple too:\n+\n+  $ stg import --mail my-mail\n+\n+The e-mail should be in standard Git mail format (which is what e.g.\n+stglink:mail[] produces) -- that is, with the patch in-line in the\n+mail, not attached. The authorship info is taken from the mail\n+headers, and the commit message is read from the 'Subject:' line and\n+the mail body.\n+\n+If you don't give a file name, the mail will be read from the standard\n+input. This means that, if your mail reader supports it, you can pipe\n+a mail directly to +stg import $$--mail$$+ and the patch will be\n+applied.\n+\n+\n+Importing a mailbox full of patches\n+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n+\n+Finally, in case importing one patch at a time is too much work,\n+stglink:import[] also accepts an entire Unix +mbox+-format mailbox,\n+either on the command line or on its standard input; just use the\n++$$--mbox$$+ flag. Each mail should contain one patch, and is imported\n+just like with +$$--mail$$+.\n+\n+Mailboxes full of patches are produced by e.g. stglink:mail[] with the\n++$$--mbox$$+ flag, but most mail readers can produce them too, meaning\n+that you can copy all the patch mails you want to apply to a separate\n+mailbox, and then import them all in one go.\n \n \n Other stuff that needs to be placed somewhere\n"},{"id":"94143","messageId":"b0943d9e0810281509r109ee2dby51ee13a250700012@mail.gmail.com","threadId":"16071","inReplyTo":"20081028204223.9539.89315.stgit@yoghurt","subject":"Re: [StGit PATCH] Tutorial: Importing patches","fromName":"Catalin Marinas","fromEmail":"catalin.marinas@gmail.com","sentAt":"2008-10-28T22:09:52Z","receivedAt":"2008-10-28T22:09:52Z","isPatch":true,"sender":{"key":"catalin.marinas@gmail.com","avatar":null},"body":"Hi Karl,\n\nThanks for the patch.\n\n2008/10/28 Karl Hasselström <kha@treskal.com>:\n> +Importing a patch from an e-mail is simple too:\n> +\n> +  $ stg import --mail my-mail\n> +\n> +The e-mail should be in standard Git mail format (which is what e.g.\n> +stglink:mail[] produces) -- that is, with the patch in-line in the\n> +mail, not attached. The authorship info is taken from the mail\n> +headers, and the commit message is read from the 'Subject:' line and\n> +the mail body.\n\nIt actually supports importing diffs from attachments as well as long\nas they are text/plain (the description is expected in the mail body).\nAnyway, I think we don't have to mention this in the tutorial as most\npeople would use the Git mail format anyway.\n\n-- \nCatalin\n"},{"id":"94174","messageId":"20081029102814.GA30762@diana.vm.bytemark.co.uk","threadId":"16071","inReplyTo":"b0943d9e0810281509r109ee2dby51ee13a250700012@mail.gmail.com","subject":"Re: [StGit PATCH] Tutorial: Importing patches","fromName":"Karl Hasselström","fromEmail":"kha@treskal.com","sentAt":"2008-10-29T10:28:14Z","receivedAt":"2008-10-29T10:28:14Z","isPatch":true,"sender":{"key":"kha@treskal.com","avatar":"https://gravatar.com/avatar/f0120c734b5279b345075a28521e1ac66acb20c9913ffe9bf6ae97e53f7f3f13?d=mp&s=160"},"body":"On 2008-10-28 22:09:52 +0000, Catalin Marinas wrote:\n\n> 2008/10/28 Karl Hasselström <kha@treskal.com>:\n\n> > +The e-mail should be in standard Git mail format (which is what e.g.\n> > +stglink:mail[] produces) -- that is, with the patch in-line in the\n> > +mail, not attached. The authorship info is taken from the mail\n> > +headers, and the commit message is read from the 'Subject:' line and\n> > +the mail body.\n>\n> It actually supports importing diffs from attachments as well as\n> long as they are text/plain (the description is expected in the mail\n> body).\n\nYeah, I had a vague recollection that that might be the case, but the\ntest suite doesn't cover it, and I've actually tried it a few times\nand it's never worked for me.\n\n> Anyway, I think we don't have to mention this in the tutorial as\n> most people would use the Git mail format anyway.\n\nYes.\n\n-- \nKarl Hasselström, kha@treskal.com\n      www.treskal.com/kalle\n"}]}