Signed-off-by: Karl Hasselström <kha@xxxxxxxxxxx> --- Documentation/tutorial.txt | 84 +++++++++++++++++++++++++++++++++++++++++++- 1 files changed, 83 insertions(+), 1 deletions(-) diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index 46c78cf..2808462 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -533,7 +533,89 @@ index e324179..6398958 100644 Rebasing a patch series ----------------------- -TODO:: rebase, ... +While you are busy writing, submitting, and revising your patch +series, other people will be doing the same thing. As a result, even +though you started writing your patches on top of what was the latest +history at the time, your stack base will grow ever more out of date. + +When you clone a repository, + + $ stg clone http://homepage.ntlworld.com/cmarinas/stgit.git stgit + +you initially get one local branch, +master+. You also get a number of +'remote' branches, one for each branch in the repository you cloned. +In the case of the StGit repository, these are ++remotes/origin/stable+, +remotes/origin/master+, and ++remotes/origin/proposed+. +remotes+ means that it's not a local +branch, just a snapshot of a branch in another repository; and ++origin+ is the default name for the first remote repository (you can +set up more; see the man page for +git remote+). + +Right after cloning, +master+ and +remotes/origin/master+ point at the +same commit. When you start writing patches, +master+ will advance, +and always point at the current topmost patch, but ++remotes/origin/master+ will stay the same because it represents the +master branch in the repository you cloned from -- your 'upstream' +repository. + +Unless you are the only one working on the project, however, the +upstream repository will not stay the same forever. New commits will +be added to its branches; to update your clone, run + + $ git remote update + +This will update all your remote branches, but won't touch your local +branches. To get the latest changes into your local +master+ branch, +use stglink:rebase[]: + + $ stg rebase remotes/origin/master + +This command will do three things: + + 1. Pop all patches, so that your local branch (+master+, in this + example) points at the stack base. This is the same commit that + +remotes/origin/master+ pointed at at the time you started + writing your patches. + + 2. Set the stack base to the given commit (the current, updated + value of +remotes/origin/master+). + + 3. Push the patches that were popped in the first step. + +The end result is that your patches are now applied on top of the +latest version of +remotes/origin/master+. + +The primary reason for rebasing is to reduce the amount of conflicts +between your work and others'. If one of your patches changes the same +part of the same file as a patch someone else has written, you will +get a conflict when you run stglink:rebase[] the next time after the +other person's patch has been accepted upstream. It is almost always +less work to rebase often and resolve these one at a time, rather than +a whole lot at once. After all, you have to rebase eventually; if you +mail out patches that are based on an outdated branch, everyone who +tries to apply them has to resolve the conflicts instead. There are +more effective ways to get popular. + + +When your patches are accepted +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If and when some or all of your patches are accepted upstream, you +update and rebase just like usual -- but be sure to use the ++$$--merged$$+ flag to stglink:rebase[]: + + $ git remote update + $ stg rebase --merged remotes/origin/master + +This flag makes the rebase operation better at detecting that your +patches have been merged, at some cost in performance. + +The patches that had been merged will still be present in your patch +stack after the rebase, but they will be empty, since the change they +added is now already present in the stack base. Run stglink:clean[] to +get rid of such empty patches if you don't want them hanging around: + + $ stg clean Importing patches -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
