patchDocumentation: Transplanting branch with git-rebase --onto

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(-)

Jakub Narebski <jnareb@gmail.com> writes:

Ok.

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:

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

Thanks for comments.

Junio C Hamano 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.

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

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 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.

[...]

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

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(-)

Jakub Narebski <jnareb@gmail.com> writes:

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.

Junio C Hamano wrote:

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

On Sun, 5 Nov 2006 11:22:17 +0100, Jakub Narebski wrote:

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.

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

Carl Worth <cworth@cworth.org> writes:

I agree with that.

Good point.