[PATCH] Improve the first rebase illustration with command example

[PATCH] Improve the first rebase illustration with command example

[Jari Aalto]

The case where rebasing need arises was not previously explained. The
first illustration was broadened to contain complete set of commands
and explanatory commentary how to synchronize current branch development
with new upstream changes.

The patch does not do justice, because the overall structure of the
manual was changes as well. Changes:

- Take out the examples from DESCRIPTION and move them after the
  OPTIONS, under new heading EXAMPLES.
- Number the examples 1, 2, 3 and make each one separate topic
- Broaden the example 1 illustration with commands.

Signed-off-by: Jari Aalto <jari.aalto@cante.net>
---
 Documentation/git-rebase.txt |  212 +++++++++++++++++++++++++-----------------
 1 files changed, 125 insertions(+), 87 deletions(-)

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index a1b6dce..71c2266 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -36,21 +36,130 @@ that caused the merge failure with `git rebase --skip`.  To restore the
 original <branch> and remove the .dotest working files, use the command
 `git rebase --abort` instead.
 
-Assume the following history exists and the current branch is "topic":
+In case of conflict, git-rebase will stop at the first problematic commit
+and leave conflict markers in the tree.  You can use git diff to locate
+the markers (<<<<<<) and make edits to resolve the conflict.  For each
+file you edit, you need to tell git that the conflict has been resolved,
+typically this would be done with
+
+
+    git add <filename>
+
+
+After resolving the conflict manually and updating the index with the
+desired resolution, you can continue the rebasing process with
+
+
+    git rebase --continue
+
+
+Alternatively, you can undo the git-rebase with
+
+
+    git rebase --abort
+
+OPTIONS
+-------
+<newbase>::
+	Starting point at which to create the new commits. If the
+	--onto option is not specified, the starting point is
+	<upstream>.  May be any valid commit, and not just an
+	existing branch name.
+
+<upstream>::
+	Upstream branch to compare against.  May be any valid commit,
+	not just an existing branch name.
+
+<branch>::
+	Working branch; defaults to HEAD.
+
+--continue::
+	Restart the rebasing process after having resolved a merge conflict.
+
+--abort::
+	Restore the original branch and abort the rebase operation.
+
+--skip::
+	Restart the rebasing process by skipping the current patch.
+
+--merge::
+	Use merging strategies to rebase.  When the recursive (default) merge
+	strategy is used, this allows rebase to be aware of renames on the
+	upstream side.
+
+-s <strategy>, \--strategy=<strategy>::
+	Use the given merge strategy; can be supplied more than
+	once to specify them in the order they should be tried.
+	If there is no `-s` option, a built-in list of strategies
+	is used instead (`git-merge-recursive` when merging a single
+	head, `git-merge-octopus` otherwise).  This implies --merge.
+
+-v, \--verbose::
+	Display a diffstat of what changed upstream since the last rebase.
+
+-C<n>::
+	Ensure at least <n> lines of surrounding context match before
+	and after each change.  When fewer lines of surrounding
+	context exist they all must match.  By default no context is
+	ever ignored.
+
+-i, \--interactive::
+	Make a list of the commits which are about to be rebased.  Let the
+	user edit that list before rebasing.
+
+-p, \--preserve-merges::
+	Instead of ignoring merges, try to recreate them.  This option
+	only works in interactive mode.
+
+include::merge-strategies.txt[]
+
+EXAMPLES
+--------
+
+EXAMPLE 1
+~~~~~~~~~
+
+Suppose you're tracking upstream development and developing a serarate
+feature that is not yet ready. You branched when upsream's HEAD was at
+E. You have progressed by 2 commits to (A,B) and working towards
+finishing commit C*. As the work is taken some time, you decide to
+update the upstream code in order to make sure you don't diverge too
+far.
+
+However, your work is unfinished and you cannot commit C* yet. We'll
+use gitlink:git-stash[1] here to assist the workflow:
 
 ------------
-          A---B---C topic
-         /
-    D---E---F---G master
+1. git stash               # Save state of branch: the incomplete C*
+2. git checkout master     # switch to master, where upstream code is
+3. git pull                # update master to: D-E + F-G (new changes)
+4. git checkout topic      # return to previous branch
+5. git rebase master       # change branch from D-E-A-B to D-E-F-G-A-B
+6. git stash apply         # Bring back previously saved state C*
+
+                 A---B---C* [1]          [4,5] A---B [6] ---C*
+                /                       /
+    master D---E ........... [2,3] F---G
 ------------
 
-From this point, the result of either of the following commands:
+The command at phase 5 `git-rebase master topic` is just a short-hand
+of `git checkout topic` followed by `git rebase master`. In the end of
+phase 6, te next commit would make working branch into
+A--B--C--X--Y--D--E--F:
 
+Note, that If D and E does not have any interaction with what A-B-C
+are attempting, there is no reason to rebase, but some people prefer
+it because rebasing tends to keep the history clearer.
 
-    git-rebase master
-    git-rebase master topic
+So, this tree
 
-would be:
+------------
+          A---B---C topic
+         /
+    D---E---F---G master
+------------
+
+was effectively converted into:
 
 ------------
                   A'--B'--C' topic
@@ -58,8 +167,8 @@ would be:
     D---E---F---G master
 ------------
 
-The latter form is just a short-hand of `git checkout topic`
-followed by `git rebase master`.
+EXAMPLE 2
+~~~~~~~~~
 
 Here is how you would transplant a topic branch based on one
 branch to another, to pretend that you forked the topic branch
@@ -94,6 +203,9 @@ We can get this using the following command:
     git-rebase --onto master next topic
 
 
+EXAMPLE 2
+~~~~~~~~~
+
 Another example of --onto option is to rebase part of a
 branch.  If we have the following situation:
 
@@ -121,6 +233,9 @@ would result in:
 
 This is useful when topicB does not depend on topicA.
 
+EXAMPLE 4
+~~~~~~~~~
+
 A range of commits could also be removed with rebase.  If we have
 the following situation:
 
@@ -142,83 +257,6 @@ This is useful if F and G were flawed in some way, or should not be
 part of topicA.  Note that the argument to --onto and the <upstream>
 parameter can be any valid commit-ish.
 
-In case of conflict, git-rebase will stop at the first problematic commit
-and leave conflict markers in the tree.  You can use git diff to locate
-the markers (<<<<<<) and make edits to resolve the conflict.  For each
-file you edit, you need to tell git that the conflict has been resolved,
-typically this would be done with
-
-
-    git add <filename>
-
-
-After resolving the conflict manually and updating the index with the
-desired resolution, you can continue the rebasing process with
-
-
-    git rebase --continue
-
-
-Alternatively, you can undo the git-rebase with
-
-
-    git rebase --abort
-
-OPTIONS
--------
-<newbase>::
-	Starting point at which to create the new commits. If the
-	--onto option is not specified, the starting point is
-	<upstream>.  May be any valid commit, and not just an
-	existing branch name.
-
-<upstream>::
-	Upstream branch to compare against.  May be any valid commit,
-	not just an existing branch name.
-
-<branch>::
-	Working branch; defaults to HEAD.
-
---continue::
-	Restart the rebasing process after having resolved a merge conflict.
-
---abort::
-	Restore the original branch and abort the rebase operation.
-
---skip::
-	Restart the rebasing process by skipping the current patch.
-
---merge::
-	Use merging strategies to rebase.  When the recursive (default) merge
-	strategy is used, this allows rebase to be aware of renames on the
-	upstream side.
-
--s <strategy>, \--strategy=<strategy>::
-	Use the given merge strategy; can be supplied more than
-	once to specify them in the order they should be tried.
-	If there is no `-s` option, a built-in list of strategies
-	is used instead (`git-merge-recursive` when merging a single
-	head, `git-merge-octopus` otherwise).  This implies --merge.
-
--v, \--verbose::
-	Display a diffstat of what changed upstream since the last rebase.
-
--C<n>::
-	Ensure at least <n> lines of surrounding context match before
-	and after each change.  When fewer lines of surrounding
-	context exist they all must match.  By default no context is
-	ever ignored.
-
--i, \--interactive::
-	Make a list of the commits which are about to be rebased.  Let the
-	user edit that list before rebasing.
-
--p, \--preserve-merges::
-	Instead of ignoring merges, try to recreate them.  This option
-	only works in interactive mode.
-
-include::merge-strategies.txt[]
-
 NOTES
 -----
 When you rebase a branch, you are changing its history in a way that
-- 
1.5.3.rc5

    Available from git repository http://cante.net/~jaalto/git/git
    Branch: Dcumentation/git-rebase.txt+assume-the-following-history+example

-- 
Welcome to FOSS revolution: we fix and modify until it shines

Re: [PATCH] Improve the first rebase illustration with command example

[Junio C Hamano]

Jari Aalto <jari.aalto@cante.net> writes:

> The case where rebasing need arises was not previously explained. The
> first illustration was broadened to contain complete set of commands
> and explanatory commentary how to synchronize current branch development
> with new upstream changes.
>
> The patch does not do justice, because the overall structure of the
> manual was changes as well. Changes:
>
> - Take out the examples from DESCRIPTION and move them after the
>   OPTIONS, under new heading EXAMPLES.
> - Number the examples 1, 2, 3 and make each one separate topic
> - Broaden the example 1 illustration with commands.
>
> Signed-off-by: Jari Aalto <jari.aalto@cante.net>

Thanks for a patch.  I tried to rebase it on top of 'master',
but then noticed a few things.

> +In case of conflict, git-rebase will stop at the first problematic commit
> +and leave conflict markers in the tree.  You can use git diff to locate
> +the markers (<<<<<<) and make edits to resolve the conflict.  For each
> +file you edit, you need to tell git that the conflict has been resolved,
> +typically this would be done with
> +
> +
> +    git add <filename>
> +
> +

Do not need nor want two blank lines around these examples; one
each should be enough.

> +After resolving the conflict manually and updating the index with the
> +desired resolution, you can continue the rebasing process with
> ...
> +Alternatively, you can undo the git-rebase with
> +
> +    git rebase --abort

That's already there in the previous paragraph that begins with
"It is possible that a merge failure will prevent this process
from being completely automatic", but I think it makes sense to
present the way you did to make each of them to stand out more.
Perhaps we would want to remove the second and later sentences
from that paragraph.

> +include::merge-strategies.txt[]
> +
> +EXAMPLES
> +--------
> +
> +EXAMPLE 1
> +~~~~~~~~~
> +
> +Suppose you're tracking upstream development and developing a serarate
> +feature that is not yet ready. You branched when upsream's HEAD was at
> +E. You have progressed by 2 commits to (A,B) and working towards
> +finishing commit C*. As the work is taken some time, you decide to
> +update the upstream code in order to make sure you don't diverge too
> +far.
> +
> +However, your work is unfinished and you cannot commit C* yet. We'll
> +use gitlink:git-stash[1] here to assist the workflow:
> +
>  ------------
> +1. git stash               # Save state of branch: the incomplete C*
> +2. git checkout master     # switch to master, where upstream code is
> +3. git pull                # update master to: D-E + F-G (new changes)
> +4. git checkout topic      # return to previous branch
> +5. git rebase master       # change branch from D-E-A-B to D-E-F-G-A-B
> +6. git stash apply         # Bring back previously saved state C*
> +
> +                 A---B---C* [1]          [4,5] A---B [6] ---C*
> +                /                       /
> +    master D---E ........... [2,3] F---G
>  ------------
>  
> +The command at phase 5 `git-rebase master topic` is just a short-hand
> +of `git checkout topic` followed by `git rebase master`. In the end of
> +phase 6, te next commit would make working branch into
> +A--B--C--X--Y--D--E--F:

You don't.  You would make D-E-F-G-A-B-C.

It would be much easier for new users to read if our examples
start from simpler and progress to more complex. It appears that
the use of stash in this example (only because the example
assumes you are in the middle of something that is unfinished)
complicates description without merit.

After the user understands the workflow that starts from having
A-B and with clean working tree, IOW, your steps 2 through 5,
managing the situation where you have that dirty state C* comes
as a very natural extension of what he already knows, and at
that point, it does not matter to your use of stash/unstash what
you do between steps 2-5.  You stash because you are going to do
anything complicated, and the details of that complicated stuff
does not matter why surrounding that sequence with stash/unstash
pair is useful.  In yet another words, the pair of steps 1 and 6
and the rest are orthogonal issues.

So what I would want to see in this example, if you wanted to
talk about the way git-stash can be used in conjunction with
git-rebase, would be something like this:

-- clipcrop -- >8 -- clipcrop --

EXAMPLE 1
~~~~~~~~~

Suppose you're tracking upstream development and developing a serarate
feature that is not yet ready. You started when upsream's HEAD was at
E. You have progressed by 2 commits to (A,B).

Because your work A and B have some interactions to what has
been done at the upstream in the meantime, you decide to update
the upstream code in order to make sure you don't diverge too
far.

------------
1. git checkout master     # switch to master, where upstream code is
2. git pull                # update master to: D-E + F-G (new changes)
3. git checkout topic      # return to previous branch
4. git rebase master       # change branch from D-E-A-B to D-E-F-G-A'-B'

                 A---B [3]            A'--B' [4]
                /                    /
    master D---E [1] ---------- F---G [2]
------------

The command at step 4 `git-rebase master topic` is just a short-hand
of `git checkout topic` followed by `git rebase master`. When
you are done, your topic branch has two commits on top of the
updated master.

Note, that If D and E does not have any interaction with what
your topic are attempting to achieve, there is no reason to
rebase, but some people prefer it because rebasing tends to keep
the history clearer.

If you are in the middle of building some more stuff on top of
B but not committed yet, rebase will refuse to run.  You can use
gitlink:git-stash[1] to help you in such a case.

------------
0. git stash
1...4 (the same as before)
5. git stash apply

                 A---B---C* [0]       A'--B'--C*
                /                    /
    master D---E [1] ---------- F---G [2]
------------

What happens to A, B, D, E, F and G is exactly the same as
before.  The only difference is that your work-in-progress
(depicted as `C*` in the above, the work you did since `B`) is
saved away first, and then reapplied on top of updated `B`.

In short, the above procedure would transform this history
structure:

------------
          A---B---C* topic
         /
    D---E---F---G* master
------------

into this:

------------
                  A'--B'--C' topic
                 /
    D---E---F---G master
------------