[PATCH/RFC] Documentation: Two more git-rebase --onto examples

[PATCH/RFC] Documentation: Two more git-rebase --onto examples

[Jakub Narebski]

Added example of transplantig feature branch from one development
branch (for example "next") into the other development branch (for
example "master").

Added example of rebasing part of branch, or transplanting feature
branch from the tip of other feature branch to the development branch
the second feature branch started from.

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
I asked for comments because I'm not native English speaker and I'm not
sure about correctness of descriptions of added examples.

P.S. Perhaps we should separate the part dealing with CONFLICT(contents)
into separate documentation file, and include it as needed (for example
alsop in git-push(1)).

 Documentation/git-rebase.txt |   55 ++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 55 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 10f2924..1308d2f 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -65,6 +65,61 @@ would be:
     D---E---F---G master
 ------------
 
+More useful example of --onto option usage include transplanting feature
+branch from one development branch to other, for example change to branch
+based off "next" branch:
+
+------------
+    o---o---o---o---o  master
+         \
+          o---o---o---o---o  next
+                           \
+                            o---o---o  topic
+------------
+
+to being a branch based off "master" branch as shown below:
+
+------------
+    o---o---o---o---o  master
+        |            \
+        |             o'--o'--o'  topic
+         \
+          o---o---o---o---o  next
+------------
+
+We can get this using the following command:
+
+    git-rebase --onto master next topic
+
+
+Yet another example of use for --onto option is to rebase part of
+branch. If we have the following situation:
+
+------------
+                            H---I---J topicB
+                           /
+                  E---F---G  topicA
+                 /
+    A---B---C---D  master
+------------
+
+then the command
+
+    git-rebase --onto master topicA topicB
+
+would give us the following situation:
+
+------------
+                 H'--I'--J'  topicB
+                /
+                | E---F---G  topicA
+                |/
+    A---B---C---D  master
+------------
+
+with "topicB" branch based off "master".
+
+
 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
-- 
1.4.3.3

Re: [PATCH/RFC] Documentation: Two more git-rebase --onto examples

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> I asked for comments because I'm not native English speaker and I'm not
> sure about correctness of descriptions of added examples.

Ok.

> +More useful example of --onto option usage include transplanting feature
> +branch from one development branch to other, for example change to branch
> +based off "next" branch:

By "more" do you mean the following examples are more useful
than the one before, or having larger number of examples adds to
the usefulness of the document overall?

How about:

        Here is how you would transplant a topic branch based on one
        branch to another, to pretend that you forked the topic branch
        from the latter branch, using `rebase --onto`.

	First let's assume your 'topic' is based on branch 'next'.

        ------------
            o---o---o---o---o  master
                 \
                  o---o---o---o---o  next
                                   \
                                    o---o---o  topic
        ------------

	We would want to make 'topic' forked from branch
	'master', like this:

> +------------
> +    o---o---o---o---o  master
> +        |            \
> +        |             o'--o'--o'  topic
> +         \
> +          o---o---o---o---o  next
> +------------
> +
> +We can get this using the following command:
> +
> +    git-rebase --onto master next topic
> +
> +
> +Yet another example of use for --onto option is to rebase part of
> +branch. If we have the following situation:

This looks the same as the original example for --onto; I would
either drop it or replace it something of different flavor.

What I find myself doing more is to reorder without using StGIT.
When I have this:

	1---2---3---4 topic

and 2 is a bit half-baked, and I would want to have:

	1---3'--4'--2' topic

I would usually do this while on "topic":

	git tag -f CG	;# "commit goal"
	git rebase --onto CG~3 CG~2 ;# plant 3 4 on top of 1
        git cherry-pick CG~2
	git diff CG ;# verify that the result matches

In ascii art, that is:

	  3'--4'
	 /
	1---2---3---4 CG

then


	  3'--4'--2' topic
	 /
	1---2---3---4 CG

Re: [PATCH/RFC] Documentation: Two more git-rebase --onto examples

[Jakub Narebski]

Thanks for comments.

Junio C Hamano wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
> 
>> +More useful example of --onto option usage include transplanting feature
>> +branch from one development branch to other, for example change to branch
>> +based off "next" branch:
> 
> By "more" do you mean the following examples are more useful
> than the one before, or having larger number of examples adds to
> the usefulness of the document overall?

I found original example somewhat artifical, but after thinking on that
I guess that the need for rebase onto master~1 might happen when the last
commit in master is for example to be amended or rebased. 

The "transplanting branch" example feels like more natural to me.

> How about:
> 
>         Here is how you would transplant a topic branch based on one
>         branch to another, to pretend that you forked the topic branch
>         from the latter branch, using `rebase --onto`.

Perhaps adding why one might want to transplant topic branch from one
development branch to other: for example when feature being developed
on topic branch relied on functionality which was at the time topic branch
was started available only in 'next' branch, but meanwhile it matured and
was merged into 'master' (more stable) branch. One would want to base
topic branches on 'master' branch if possible.

[...]
> This looks the same as the original example for --onto; I would
> either drop it or replace it something of different flavor.

This example is from latest post by Andy Parkins, which asked how to
do that. But I find your example as being better, because it shows
even more power of core git history manipulation.

> What I find myself doing more is to reorder without using StGIT.
> When I have this:
> 
> 	1---2---3---4 topic
> 
> and 2 is a bit half-baked, and I would want to have:
> 
> 	1---3'--4'--2' topic
[...]

Here I find lack of --interactive option to at least git-am based
rebase; git-rebase could simply pass --interactive option to git-am.

-- 
Jakub Narebski

[PATCH] Documentation: Transplanting branch with git-rebase --onto

[Jakub Narebski]

Added example of transplantig feature branch from one development
branch (for example "next") into the other development branch (for
example "master").

[jn: with a little help from Junio]

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
What about this?

The second example I think has place in tutorial or GitTips on GitWiki


 Documentation/git-rebase.txt |   34 ++++++++++++++++++++++++++++++++++
 1 files changed, 34 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 10f2924..9e822c5 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -65,6 +65,40 @@ would be:
     D---E---F---G master
 ------------
 
+
+Here is how you would transplant a topic branch based on one
+branch to another, to pretend that you forked the topic branch
+from the latter branch, using `rebase --onto`.
+
+First let's assume your 'topic' is based on branch 'next'.
+For example feature developed in 'topic' depends on some
+functionality which is found in 'next'.
+
+------------
+    o---o---o---o---o  master
+         \
+          o---o---o---o---o  next
+                           \
+                            o---o---o  topic
+------------
+
+We would want to make 'topic' forked from branch 'master',
+for example because the functionality 'topic' branch depend on
+got merged into more stable 'master' branch, like this:
+
+------------
+    o---o---o---o---o  master
+        |            \
+        |             o'--o'--o'  topic
+         \
+          o---o---o---o---o  next
+------------
+
+We can get this using the following command:
+
+    git-rebase --onto master next 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
-- 
1.4.3.4

Re: [PATCH] Documentation: Transplanting branch with git-rebase --onto

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> Added example of transplantig feature branch from one development
> branch (for example "next") into the other development branch (for
> example "master").
>
> [jn: with a little help from Junio]
>
> Signed-off-by: Jakub Narebski <jnareb@gmail.com>
> ---
> What about this?

I agree with Carl that the original example of --onto was not
clear why it is a good thing, so I am inclined to follow his
suggestion and drop the original example and keep your second
one yanked from your try#1 patch when committing, if it is Ok
with you.

Re: [PATCH] Documentation: Transplanting branch with git-rebase --onto

[Jakub Narebski]

Junio C Hamano wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
> 
>> Added example of transplantig feature branch from one development
>> branch (for example "next") into the other development branch (for
>> example "master").
>>
>> [jn: with a little help from Junio]
>>
>> Signed-off-by: Jakub Narebski <jnareb@gmail.com>
>> ---
>> What about this?
> 
> I agree with Carl that the original example of --onto was not
> clear why it is a good thing, so I am inclined to follow his
> suggestion and drop the original example and keep your second
> one yanked from your try#1 patch when committing, if it is Ok
> with you.

That's O.K. by me. 

Perhaps you can add the info that git-rebase with <branch> argument 
switches to given branch (is equivalent to checkout + rebase without
<branch> argument).

P.S. The "transplanting from 'next' to 'master'" example was taken from 
your mail, Junio:
  Message-ID: <7vlkrfoaky.fsf@assigned-by-dhcp.cox.net>
  http://permalink.gmane.org/gmane.comp.version-control.git/22923

-- 
Jakub Narebski

Re: [PATCH/RFC] Documentation: Two more git-rebase --onto examples

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 1573 bytes --]

On Sun, 5 Nov 2006 11:22:17 +0100, Jakub Narebski wrote:
> I found original example somewhat artifical, but after thinking on that
> I guess that the need for rebase onto master~1 might happen when the last
> commit in master is for example to be amended or rebased.

It is quite artificial in presentation at least. There's no motivating
explanation of what is being attempted just before-and-after diagrams
along with a command that achieves the result. That presentation makes
it very hard to learn how to usefully use the command from the
description.

> > This looks the same as the original example for --onto; I would
> > either drop it or replace it something of different flavor.
>
> This example is from latest post by Andy Parkins, which asked how to
> do that. But I find your example as being better, because it shows
> even more power of core git history manipulation.

I think Jakub's explanations do a much better job of explaining
something someone might actually want to do and then showing how to do
it. So if there's redundancy I'd vote for dropping the old stuff.

Meanwhile, while we're talking about git-rebase documentation, the
recent posts about the:

	git rebase --onto <foo> <upstream> <branch>

form take advantage of the fact that this command also changes the
current branch to <branch>. I think that's quite surprising behavior,
(though useful in the example that was given). It's perhaps out of
line with the scope of git-rebase but it should at least be
documented. I think that will need some specific mention before the
examples.

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [PATCH/RFC] Documentation: Two more git-rebase --onto examples

[Junio C Hamano]

Carl Worth <cworth@cworth.org> writes:

> I think Jakub's explanations do a much better job of explaining
> something someone might actually want to do and then showing how to do
> it. So if there's redundancy I'd vote for dropping the old stuff.

I agree with that.

> Meanwhile, while we're talking about git-rebase documentation, the
> recent posts about the:
>
> 	git rebase --onto <foo> <upstream> <branch>
>
> form take advantage of the fact that this command also changes the
> current branch to <branch>. I think that's quite surprising behavior,
> (though useful in the example that was given). It's perhaps out of
> line with the scope of git-rebase but it should at least be
> documented. I think that will need some specific mention before the
> examples.

Good point.