Skip to contentSkip to conversation

Documentation: Two more git-rebase --onto examples

PATCH/RFC In review Jakub Narebski 3 participants 8 messages Aug 11, 2016 Documentation

lore
Share & tools
lore
#3 lore raw

PATCH 1/1 Documentation: Transplanting branch with git-rebase --onto

In reply to 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]

---
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(-)
Documentation/git-rebase.txt +34 -0
index 10f2924..9e822c5 100644
@@ -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
Signature · 1 line
1.4.3.4
#0 lore raw

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.

---
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(-)
Documentation/git-rebase.txt +55 -0
index 10f2924..1308d2f 100644
@@ -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
Signature · 1 line
1.4.3.3
#1 lore raw
Quoted 2 lines · Jakub Narebski

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

Ok.

Documentation/git-rebase.txt would be: · line 70

Quoted 3 lines
Documentation/git-rebase.txt +3 -0
+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:
Quoted 5 lines

+------------

Documentation/git-rebase.txt +4 -0
+    o---o---o---o---o  master
+        |            \
+        |             o'--o'--o'  topic
+         \

Documentation/git-rebase.txt would be: · line 96

Quoted 10 lines
Documentation/git-rebase.txt +10 -0
+          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
#2 lore raw

Thanks for comments.

Quoted 9 lines · Junio C Hamano

Documentation/git-rebase.txt would be: · line 70

Quoted 3 lines · Jakub Narebski
Documentation/git-rebase.txt +3 -0
+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.

Quoted 5 lines

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.

[...]

Quoted 2 lines

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.

Quoted 8 lines

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.

Signature · 1 line
Jakub Narebski
#4 lore raw

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

In reply to Jakub Narebski
Quoted 9 lines · 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]

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

#6 lore raw
In reply to Jakub Narebski
Quoted 3 lines · Jakub Narebski

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.

Quoted 6 lines
Quoted 2 lines

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

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (GNU/Linux)

iD8DBQBFT3uV6JDdNq8qSWgRAu9KAJ9V6bnEp3hWx9eCTqxoLBUAZtS1zwCgm3Ev HWQz+sZZ4OyT63eEGUnv1GY=
=wvTm
-----END PGP SIGNATURE-----

#5 lore raw

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

In reply to Junio C Hamano
Quoted 12 lines · Junio C Hamano
Quoted 9 lines · 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]

---
What about this?

Quoted 5 lines

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: <[email protected]>
http://permalink.gmane.org/gmane.comp.version-control.git/22923

Signature · 1 line
Jakub Narebski
#7 lore raw
In reply to Carl Worth
Quoted 3 lines · Carl Worth

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.

Quoted 11 lines

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.