{"thread":{"id":"15869","subject":"[StGit PATCH 3/4] Tutorial: Cover \"stg mail\"","startedAt":"2008-10-12T15:11:08Z","lastAt":"2008-10-12T22:10:04Z","messageCount":6,"participants":["Karl Hasselström","Catalin Marinas"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"92850","messageId":"20081012150825.17648.3315.stgit@yoghurt","threadId":"15869","inReplyTo":null,"subject":"[StGit PATCH 0/4] More tutorial updates","fromName":"Karl Hasselström","fromEmail":"kha@treskal.com","sentAt":"2008-10-12T15:11:08Z","receivedAt":"2008-10-12T15:11:08Z","isPatch":true,"sender":{"key":"kha@treskal.com","avatar":"https://gravatar.com/avatar/f0120c734b5279b345075a28521e1ac66acb20c9913ffe9bf6ae97e53f7f3f13?d=mp&s=160"},"body":"More updates to the tutorial. I'd really appreciate if people would\nsanity check these; a bad tutorial tends to reflect negatively on a\nproject.\n\n---\n\nKarl Hasselström (4):\n      Tutorial: Write about rebasing\n      Tutorial: Cover \"stg mail\"\n      Tutorial: Explain diffs a little bit better\n      Tutorial: Talk about conflicts when introducing StGit\n\n\n Documentation/stg.txt      |    8 ++\n Documentation/tutorial.txt |  191 ++++++++++++++++++++++++++++++++++++++++++--\n 2 files changed, 191 insertions(+), 8 deletions(-)\n\n-- \nKarl Hasselström, kha@treskal.com\n      www.treskal.com/kalle\n"},{"id":"92847","messageId":"20081012151133.17648.7945.stgit@yoghurt","threadId":"15869","inReplyTo":"20081012150825.17648.3315.stgit@yoghurt","subject":"[StGit PATCH 1/4] Tutorial: Talk about conflicts when introducing StGit","fromName":"Karl Hasselström","fromEmail":"kha@treskal.com","sentAt":"2008-10-12T15:11:33Z","receivedAt":"2008-10-12T15:11:33Z","isPatch":true,"sender":{"key":"kha@treskal.com","avatar":"https://gravatar.com/avatar/f0120c734b5279b345075a28521e1ac66acb20c9913ffe9bf6ae97e53f7f3f13?d=mp&s=160"},"body":"Conflicts and conflict resolving are essential features of StGit, so\nwe'd better tell the user about them.\n\nSigned-off-by: Karl Hasselström <kha@treskal.com>\n\n---\n\n Documentation/stg.txt |    8 ++++++++\n 1 files changed, 8 insertions(+), 0 deletions(-)\n\n\ndiff --git a/Documentation/stg.txt b/Documentation/stg.txt\nindex 5973a6b..fc8fd7c 100644\n--- a/Documentation/stg.txt\n+++ b/Documentation/stg.txt\n@@ -38,6 +38,14 @@ to maintain a 'patch stack' on top of a Git branch:\n     an updated branch, you can take all your patches and apply them on\n     top of the updated branch.\n \n+  * As you would expect, changing what is below a patch can cause that\n+    patch to no longer apply cleanly -- this can occur when you\n+    reorder patches, rebase patches, or refresh a non-topmost patch.\n+    StGit uses Git's rename-aware three-way merge capability to\n+    automatically fix up what it can; if it still fails, it lets you\n+    manually resolve the conflict just like you would resolve a merge\n+    conflict in Git.\n+\n   * The patch stack is just some extra metadata attached to regular\n     Git commits, so you can continue to use most Git tools along with\n     StGit.\n"},{"id":"92849","messageId":"20081012151139.17648.28282.stgit@yoghurt","threadId":"15869","inReplyTo":"20081012150825.17648.3315.stgit@yoghurt","subject":"[StGit PATCH 2/4] Tutorial: Explain diffs a little bit better","fromName":"Karl Hasselström","fromEmail":"kha@treskal.com","sentAt":"2008-10-12T15:11:39Z","receivedAt":"2008-10-12T15:11:39Z","isPatch":true,"sender":{"key":"kha@treskal.com","avatar":"https://gravatar.com/avatar/f0120c734b5279b345075a28521e1ac66acb20c9913ffe9bf6ae97e53f7f3f13?d=mp&s=160"},"body":"Say that we use unified diffs, and point to the Wikipedia article\nabout them. We should probably explain this in more detail ourselves\nwhen we get a proper user guide; but for the tutorial, this is\nprobably enough.\n\nSigned-off-by: Karl Hasselström <kha@treskal.com>\n\n---\n\n Documentation/tutorial.txt |    9 +++++----\n 1 files changed, 5 insertions(+), 4 deletions(-)\n\n\ndiff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt\nindex 103f3e4..e9d8b22 100644\n--- a/Documentation/tutorial.txt\n+++ b/Documentation/tutorial.txt\n@@ -103,10 +103,11 @@ And voilà -- the patch is no longer empty:\n            _main()\n        finally:\n \n-(I'm assuming you're already familiar with patches like this from Git,\n-but it's really quite simple; in this example, I've added the +$$print\n-'My first patch!'$$+ line to the file +stgit/main.py+, at around line\n-171.)\n+(I'm assuming you're already familiar with\n+htmllink:http://en.wikipedia.org/wiki/Diff#Unified_format[unified\n+diff] patches like this from Git, but it's really quite simple; in\n+this example, I've added the +$$print 'My first patch!'$$+ line to the\n+file +stgit/main.py+, at around line 171.)\n \n Since the patch is also a regular Git commit, you can also look at it\n with regular Git tools such as manlink:gitk[].\n"},{"id":"92846","messageId":"20081012151145.17648.59668.stgit@yoghurt","threadId":"15869","inReplyTo":"20081012150825.17648.3315.stgit@yoghurt","subject":"[StGit PATCH 3/4] Tutorial: Cover \"stg mail\"","fromName":"Karl Hasselström","fromEmail":"kha@treskal.com","sentAt":"2008-10-12T15:11:45Z","receivedAt":"2008-10-12T15:11:45Z","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 |  100 ++++++++++++++++++++++++++++++++++++++++++--\n 1 files changed, 96 insertions(+), 4 deletions(-)\n\n\ndiff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt\nindex e9d8b22..46c78cf 100644\n--- a/Documentation/tutorial.txt\n+++ b/Documentation/tutorial.txt\n@@ -431,17 +431,109 @@ patches as patches.\n Workflow: Tracking branch\n =========================\n \n+In the 'Development branch' workflow described above, we didn't have\n+to worry about other people; we're working on our branch, they are\n+presumably working on theirs, and when the time comes and we're ready\n+to publish our branch, we'll probably end up merging our branch with\n+those other peoples'. That's how Git is designed to work.\n \n-Rebasing a patch series\n------------------------\n+Or rather, one of the ways Git is designed to work. An alternative,\n+popular in e.g. the Linux kernel community (for which Git was\n+originally created), is that contributors send their patches by e-mail\n+to a mailing list. Others read the patches, try them out, and provide\n+feedback; often, the patch author is asked to send a new and improved\n+version of the patches. Once the project maintainer is satisfied that\n+the patches are good, she'll 'apply' them to a branch and publish it.\n \n-TODO:: rebase, ...\n+StGit is ideally suited for the process of creating patches, mailing\n+them out for review, revising them, mailing them off again, and\n+eventually getting them accepted.\n \n \n Getting patches upstream\n ------------------------\n \n-TODO:: export, mail, ...\n+We've already covered how to clone a Git repository and start writing\n+patches. As for the next step, there are two commands you might use to\n+get patches out of StGit: stglink:mail[] and stglink:export[].\n+stglink:export[] will export your patches to a filesystem directory as\n+one text file per patch, which can be useful if you are going to send\n+the patches by something other than e-mail. Most of the time, though,\n+stglink:mail[] is what you want.\n+\n+NOTE: Git comes with tools for sending commits via e-mail. Since StGit\n+patches are Git commits, you can use the Git tools if you like them\n+better for some reason.\n+\n+NOTE: For exporting single patches -- as opposed to a whole bunch of\n+them -- you could also use stglink:show[] or stglink:diff[].\n+\n+Mailing a patch is as easy as this:\n+\n+  $ stg mail --to recipient@example.com <patches>\n+\n+You can list one or more patches, or ranges of patches. Each patch\n+will be sent as a separate mail, with the first line of the commit\n+message as subject line. Try mailing patches to yourself to see what\n+the result looks like.\n+\n+NOTE: stglink:mail[] uses +sendmail+ on your computer to send the\n+mails. If you don't have +sendmail+ properly set up, you can instruct\n+it to use any SMTP server with the +$$--smtp-server$$+ flag.\n+\n+There are many command-line options to control exactly how mails are\n+sent, as well as a message template you can modify if you want. The\n+man page has all the details; I'll just mention two more here.\n+\n++$$--edit-cover$$+ will open an editor and let you write an\n+introductory message; all the patch mails will then be sent as replies\n+to this 'cover message'. This is usually a good idea if you send more\n+than one patch, so that reviewers can get a quick overview of the\n+patches you sent.\n+\n++$$--edit-patches$$+ will let you edit each patch before it is sent.\n+You can change anything, but note that you are only editing the\n+outgoing mail, not the patch itself; if you want to make changes to\n+the patch, you probably want to use the regular StGit commands to do\n+so. What this 'is' useful for, though, is to add notes for the patch\n+recipients:\n+\n+----------------------------------------------------------------------\n+From: Audrey U. Thor <author@example.com>\n+Subject: [PATCH] First line of the commit message\n+\n+The rest of the commit message\n+\n+---\n+\n+Everything after the line with the three dashes and before the diff is\n+just a comment, and not part of the commit message. If there's\n+anything you want the patch recipients to see, but that shouldn't be\n+recorded in the history if the patch is accepted, write it here.\n+\n+ stgit/main.py |    1 +\n+ 1 files changed, 1 insertions(+), 0 deletions(-)\n+\n+\n+diff --git a/stgit/main.py b/stgit/main.py\n+index e324179..6398958 100644\n+--- a/stgit/main.py\n++++ b/stgit/main.py\n+@@ -171,6 +171,7 @@ def _main():\n+     sys.exit(ret or utils.STGIT_SUCCESS)\n+\n+ def main():\n++    print 'My first patch!'\n+     try:\n+         _main()\n+     finally:\n+----------------------------------------------------------------------\n+\n+\n+Rebasing a patch series\n+-----------------------\n+\n+TODO:: rebase, ...\n \n \n Importing patches\n"},{"id":"92848","messageId":"20081012151151.17648.46373.stgit@yoghurt","threadId":"15869","inReplyTo":"20081012150825.17648.3315.stgit@yoghurt","subject":"[StGit PATCH 4/4] Tutorial: Write about rebasing","fromName":"Karl Hasselström","fromEmail":"kha@treskal.com","sentAt":"2008-10-12T15:11:51Z","receivedAt":"2008-10-12T15:11:51Z","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 |   84 +++++++++++++++++++++++++++++++++++++++++++-\n 1 files changed, 83 insertions(+), 1 deletions(-)\n\n\ndiff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt\nindex 46c78cf..2808462 100644\n--- a/Documentation/tutorial.txt\n+++ b/Documentation/tutorial.txt\n@@ -533,7 +533,89 @@ index e324179..6398958 100644\n Rebasing a patch series\n -----------------------\n \n-TODO:: rebase, ...\n+While you are busy writing, submitting, and revising your patch\n+series, other people will be doing the same thing. As a result, even\n+though you started writing your patches on top of what was the latest\n+history at the time, your stack base will grow ever more out of date.\n+\n+When you clone a repository,\n+\n+  $ stg clone http://homepage.ntlworld.com/cmarinas/stgit.git stgit\n+\n+you initially get one local branch, +master+. You also get a number of\n+'remote' branches, one for each branch in the repository you cloned.\n+In the case of the StGit repository, these are\n++remotes/origin/stable+, +remotes/origin/master+, and\n++remotes/origin/proposed+. +remotes+ means that it's not a local\n+branch, just a snapshot of a branch in another repository; and\n++origin+ is the default name for the first remote repository (you can\n+set up more; see the man page for +git remote+).\n+\n+Right after cloning, +master+ and +remotes/origin/master+ point at the\n+same commit. When you start writing patches, +master+ will advance,\n+and always point at the current topmost patch, but\n++remotes/origin/master+ will stay the same because it represents the\n+master branch in the repository you cloned from -- your 'upstream'\n+repository.\n+\n+Unless you are the only one working on the project, however, the\n+upstream repository will not stay the same forever. New commits will\n+be added to its branches; to update your clone, run\n+\n+  $ git remote update\n+\n+This will update all your remote branches, but won't touch your local\n+branches. To get the latest changes into your local +master+ branch,\n+use stglink:rebase[]:\n+\n+  $ stg rebase remotes/origin/master\n+\n+This command will do three things:\n+\n+  1. Pop all patches, so that your local branch (+master+, in this\n+     example) points at the stack base. This is the same commit that\n+     +remotes/origin/master+ pointed at at the time you started\n+     writing your patches.\n+\n+  2. Set the stack base to the given commit (the current, updated\n+     value of +remotes/origin/master+).\n+\n+  3. Push the patches that were popped in the first step.\n+\n+The end result is that your patches are now applied on top of the\n+latest version of +remotes/origin/master+.\n+\n+The primary reason for rebasing is to reduce the amount of conflicts\n+between your work and others'. If one of your patches changes the same\n+part of the same file as a patch someone else has written, you will\n+get a conflict when you run stglink:rebase[] the next time after the\n+other person's patch has been accepted upstream. It is almost always\n+less work to rebase often and resolve these one at a time, rather than\n+a whole lot at once. After all, you have to rebase eventually; if you\n+mail out patches that are based on an outdated branch, everyone who\n+tries to apply them has to resolve the conflicts instead. There are\n+more effective ways to get popular.\n+\n+\n+When your patches are accepted\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+If and when some or all of your patches are accepted upstream, you\n+update and rebase just like usual -- but be sure to use the\n++$$--merged$$+ flag to stglink:rebase[]:\n+\n+  $ git remote update\n+  $ stg rebase --merged remotes/origin/master\n+\n+This flag makes the rebase operation better at detecting that your\n+patches have been merged, at some cost in performance.\n+\n+The patches that had been merged will still be present in your patch\n+stack after the rebase, but they will be empty, since the change they\n+added is now already present in the stack base. Run stglink:clean[] to\n+get rid of such empty patches if you don't want them hanging around:\n+\n+  $ stg clean\n \n \n Importing patches\n"},{"id":"92879","messageId":"b0943d9e0810121510p3aa1d9fbo232a24c6c8ee223a@mail.gmail.com","threadId":"15869","inReplyTo":"20081012150825.17648.3315.stgit@yoghurt","subject":"Re: [StGit PATCH 0/4] More tutorial updates","fromName":"Catalin Marinas","fromEmail":"catalin.marinas@gmail.com","sentAt":"2008-10-12T22:10:04Z","receivedAt":"2008-10-12T22:10:04Z","isPatch":true,"sender":{"key":"catalin.marinas@gmail.com","avatar":null},"body":"2008/10/12 Karl Hasselström <kha@treskal.com>:\n> More updates to the tutorial. I'd really appreciate if people would\n> sanity check these; a bad tutorial tends to reflect negatively on a\n> project.\n\nI merge kha/safe into master and I'll post patches against it. Thanks.\n\n-- \nCatalin\n"}]}