{"thread":{"id":"9738","subject":"[PATCH] Improve the first rebase illustration with command example","startedAt":"2007-09-01T10:58:28Z","lastAt":"2007-09-01T20:04:34Z","messageCount":2,"participants":["Jari Aalto","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"52139","messageId":"bqcmsld7.fsf@cante.net","threadId":"9738","inReplyTo":null,"subject":"[PATCH] Improve the first rebase illustration with command example","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2007-09-01T10:58:28Z","receivedAt":"2007-09-01T10:58:28Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"The case where rebasing need arises was not previously explained. The\nfirst illustration was broadened to contain complete set of commands\nand explanatory commentary how to synchronize current branch development\nwith new upstream changes.\n\nThe patch does not do justice, because the overall structure of the\nmanual was changes as well. Changes:\n\n- Take out the examples from DESCRIPTION and move them after the\n OPTIONS, under new heading EXAMPLES.\n- Number the examples 1, 2, 3 and make each one separate topic\n- Broaden the example 1 illustration with commands.\n\nSigned-off-by: Jari Aalto \n---\n Documentation/git-rebase.txt | 212 +++++++++++++++++++++++++-----------------\n 1 files changed, 125 insertions(+), 87 deletions(-)\n\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex a1b6dce..71c2266 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -36,21 +36,130 @@ that caused the merge failure with `git rebase --skip`. To restore the\n original and remove the .dotest working files, use the command\n `git rebase --abort` instead.\n \n-Assume the following history exists and the current branch is \"topic\":\n+In case of conflict, git-rebase will stop at the first problematic commit\n+and leave conflict markers in the tree. You can use git diff to locate\n+the markers (<<<<<<) and make edits to resolve the conflict. For each\n+file you edit, you need to tell git that the conflict has been resolved,\n+typically this would be done with\n+\n+\n+ git add \n+\n+\n+After resolving the conflict manually and updating the index with the\n+desired resolution, you can continue the rebasing process with\n+\n+\n+ git rebase --continue\n+\n+\n+Alternatively, you can undo the git-rebase with\n+\n+\n+ git rebase --abort\n+\n+OPTIONS\n+-------\n+::\n+\tStarting point at which to create the new commits. If the\n+\t--onto option is not specified, the starting point is\n+\t. May be any valid commit, and not just an\n+\texisting branch name.\n+\n+::\n+\tUpstream branch to compare against. May be any valid commit,\n+\tnot just an existing branch name.\n+\n+::\n+\tWorking branch; defaults to HEAD.\n+\n+--continue::\n+\tRestart the rebasing process after having resolved a merge conflict.\n+\n+--abort::\n+\tRestore the original branch and abort the rebase operation.\n+\n+--skip::\n+\tRestart the rebasing process by skipping the current patch.\n+\n+--merge::\n+\tUse merging strategies to rebase. When the recursive (default) merge\n+\tstrategy is used, this allows rebase to be aware of renames on the\n+\tupstream side.\n+\n+-s , \\--strategy=::\n+\tUse the given merge strategy; can be supplied more than\n+\tonce to specify them in the order they should be tried.\n+\tIf there is no `-s` option, a built-in list of strategies\n+\tis used instead (`git-merge-recursive` when merging a single\n+\thead, `git-merge-octopus` otherwise). This implies --merge.\n+\n+-v, \\--verbose::\n+\tDisplay a diffstat of what changed upstream since the last rebase.\n+\n+-C::\n+\tEnsure at least lines of surrounding context match before\n+\tand after each change. When fewer lines of surrounding\n+\tcontext exist they all must match. By default no context is\n+\tever ignored.\n+\n+-i, \\--interactive::\n+\tMake a list of the commits which are about to be rebased. Let the\n+\tuser edit that list before rebasing.\n+\n+-p, \\--preserve-merges::\n+\tInstead of ignoring merges, try to recreate them. This option\n+\tonly works in interactive mode.\n+\n+include::merge-strategies.txt[]\n+\n+EXAMPLES\n+--------\n+\n+EXAMPLE 1\n+~~~~~~~~~\n+\n+Suppose you're tracking upstream development and developing a serarate\n+feature that is not yet ready. You branched when upsream's HEAD was at\n+E. You have progressed by 2 commits to (A,B) and working towards\n+finishing commit C*. As the work is taken some time, you decide to\n+update the upstream code in order to make sure you don't diverge too\n+far.\n+\n+However, your work is unfinished and you cannot commit C* yet. We'll\n+use gitlink:git-stash[1] here to assist the workflow:\n \n ------------\n- A---B---C topic\n- /\n- D---E---F---G master\n+1. git stash # Save state of branch: the incomplete C*\n+2. git checkout master # switch to master, where upstream code is\n+3. git pull # update master to: D-E + F-G (new changes)\n+4. git checkout topic # return to previous branch\n+5. git rebase master # change branch from D-E-A-B to D-E-F-G-A-B\n+6. git stash apply # Bring back previously saved state C*\n+\n+ A---B---C* [1] [4,5] A---B [6] ---C*\n+ / /\n+ master D---E ........... [2,3] F---G\n ------------\n \n-From this point, the result of either of the following commands:\n+The command at phase 5 `git-rebase master topic` is just a short-hand\n+of `git checkout topic` followed by `git rebase master`. In the end of\n+phase 6, te next commit would make working branch into\n+A--B--C--X--Y--D--E--F:\n \n+Note, that If D and E does not have any interaction with what A-B-C\n+are attempting, there is no reason to rebase, but some people prefer\n+it because rebasing tends to keep the history clearer.\n \n- git-rebase master\n- git-rebase master topic\n+So, this tree\n \n-would be:\n+------------\n+ A---B---C topic\n+ /\n+ D---E---F---G master\n+------------\n+\n+was effectively converted into:\n \n ------------\n A'--B'--C' topic\n@@ -58,8 +167,8 @@ would be:\n D---E---F---G master\n ------------\n \n-The latter form is just a short-hand of `git checkout topic`\n-followed by `git rebase master`.\n+EXAMPLE 2\n+~~~~~~~~~\n \n Here is how you would transplant a topic branch based on one\n branch to another, to pretend that you forked the topic branch\n@@ -94,6 +203,9 @@ We can get this using the following command:\n git-rebase --onto master next topic\n \n \n+EXAMPLE 2\n+~~~~~~~~~\n+\n Another example of --onto option is to rebase part of a\n branch. If we have the following situation:\n \n@@ -121,6 +233,9 @@ would result in:\n \n This is useful when topicB does not depend on topicA.\n \n+EXAMPLE 4\n+~~~~~~~~~\n+\n A range of commits could also be removed with rebase. If we have\n the following situation:\n \n@@ -142,83 +257,6 @@ This is useful if F and G were flawed in some way, or should not be\n part of topicA. Note that the argument to --onto and the \n parameter can be any valid commit-ish.\n \n-In case of conflict, git-rebase will stop at the first problematic commit\n-and leave conflict markers in the tree. You can use git diff to locate\n-the markers (<<<<<<) and make edits to resolve the conflict. For each\n-file you edit, you need to tell git that the conflict has been resolved,\n-typically this would be done with\n-\n-\n- git add \n-\n-\n-After resolving the conflict manually and updating the index with the\n-desired resolution, you can continue the rebasing process with\n-\n-\n- git rebase --continue\n-\n-\n-Alternatively, you can undo the git-rebase with\n-\n-\n- git rebase --abort\n-\n-OPTIONS\n--------\n-::\n-\tStarting point at which to create the new commits. If the\n-\t--onto option is not specified, the starting point is\n-\t. May be any valid commit, and not just an\n-\texisting branch name.\n-\n-::\n-\tUpstream branch to compare against. May be any valid commit,\n-\tnot just an existing branch name.\n-\n-::\n-\tWorking branch; defaults to HEAD.\n-\n---continue::\n-\tRestart the rebasing process after having resolved a merge conflict.\n-\n---abort::\n-\tRestore the original branch and abort the rebase operation.\n-\n---skip::\n-\tRestart the rebasing process by skipping the current patch.\n-\n---merge::\n-\tUse merging strategies to rebase. When the recursive (default) merge\n-\tstrategy is used, this allows rebase to be aware of renames on the\n-\tupstream side.\n-\n--s , \\--strategy=::\n-\tUse the given merge strategy; can be supplied more than\n-\tonce to specify them in the order they should be tried.\n-\tIf there is no `-s` option, a built-in list of strategies\n-\tis used instead (`git-merge-recursive` when merging a single\n-\thead, `git-merge-octopus` otherwise). This implies --merge.\n-\n--v, \\--verbose::\n-\tDisplay a diffstat of what changed upstream since the last rebase.\n-\n--C::\n-\tEnsure at least lines of surrounding context match before\n-\tand after each change. When fewer lines of surrounding\n-\tcontext exist they all must match. By default no context is\n-\tever ignored.\n-\n--i, \\--interactive::\n-\tMake a list of the commits which are about to be rebased. Let the\n-\tuser edit that list before rebasing.\n-\n--p, \\--preserve-merges::\n-\tInstead of ignoring merges, try to recreate them. This option\n-\tonly works in interactive mode.\n-\n-include::merge-strategies.txt[]\n-\n NOTES\n -----\n When you rebase a branch, you are changing its history in a way that\n-- \n1.5.3.rc5\n\n Available from git repository http://cante.net/~jaalto/git/git\n Branch: Dcumentation/git-rebase.txt+assume-the-following-history+example\n\n-- \nWelcome to FOSS revolution: we fix and modify until it shines\n"},{"id":"52151","messageId":"7vy7fqqhil.fsf@gitster.siamese.dyndns.org","threadId":"9738","inReplyTo":"bqcmsld7.fsf@cante.net","subject":"Re: [PATCH] Improve the first rebase illustration with command example","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-09-01T20:04:34Z","receivedAt":"2007-09-01T20:04:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jari Aalto writes:\n\n> The case where rebasing need arises was not previously explained. The\n> first illustration was broadened to contain complete set of commands\n> and explanatory commentary how to synchronize current branch development\n> with new upstream changes.\n>\n> The patch does not do justice, because the overall structure of the\n> manual was changes as well. Changes:\n>\n> - Take out the examples from DESCRIPTION and move them after the\n> OPTIONS, under new heading EXAMPLES.\n> - Number the examples 1, 2, 3 and make each one separate topic\n> - Broaden the example 1 illustration with commands.\n>\n> Signed-off-by: Jari Aalto \n\nThanks for a patch. I tried to rebase it on top of 'master',\nbut then noticed a few things.\n\n> +In case of conflict, git-rebase will stop at the first problematic commit\n> +and leave conflict markers in the tree. You can use git diff to locate\n> +the markers (<<<<<<) and make edits to resolve the conflict. For each\n> +file you edit, you need to tell git that the conflict has been resolved,\n> +typically this would be done with\n> +\n> +\n> + git add \n> +\n> +\n\nDo not need nor want two blank lines around these examples; one\neach should be enough.\n\n> +After resolving the conflict manually and updating the index with the\n> +desired resolution, you can continue the rebasing process with\n> ...\n> +Alternatively, you can undo the git-rebase with\n> +\n> + git rebase --abort\n\nThat's already there in the previous paragraph that begins with\n\"It is possible that a merge failure will prevent this process\nfrom being completely automatic\", but I think it makes sense to\npresent the way you did to make each of them to stand out more.\nPerhaps we would want to remove the second and later sentences\nfrom that paragraph.\n\n> +include::merge-strategies.txt[]\n> +\n> +EXAMPLES\n> +--------\n> +\n> +EXAMPLE 1\n> +~~~~~~~~~\n> +\n> +Suppose you're tracking upstream development and developing a serarate\n> +feature that is not yet ready. You branched when upsream's HEAD was at\n> +E. You have progressed by 2 commits to (A,B) and working towards\n> +finishing commit C*. As the work is taken some time, you decide to\n> +update the upstream code in order to make sure you don't diverge too\n> +far.\n> +\n> +However, your work is unfinished and you cannot commit C* yet. We'll\n> +use gitlink:git-stash[1] here to assist the workflow:\n> +\n> ------------\n> +1. git stash # Save state of branch: the incomplete C*\n> +2. git checkout master # switch to master, where upstream code is\n> +3. git pull # update master to: D-E + F-G (new changes)\n> +4. git checkout topic # return to previous branch\n> +5. git rebase master # change branch from D-E-A-B to D-E-F-G-A-B\n> +6. git stash apply # Bring back previously saved state C*\n> +\n> + A---B---C* [1] [4,5] A---B [6] ---C*\n> + / /\n> + master D---E ........... [2,3] F---G\n> ------------\n> \n> +The command at phase 5 `git-rebase master topic` is just a short-hand\n> +of `git checkout topic` followed by `git rebase master`. In the end of\n> +phase 6, te next commit would make working branch into\n> +A--B--C--X--Y--D--E--F:\n\nYou don't. You would make D-E-F-G-A-B-C.\n\nIt would be much easier for new users to read if our examples\nstart from simpler and progress to more complex. It appears that\nthe use of stash in this example (only because the example\nassumes you are in the middle of something that is unfinished)\ncomplicates description without merit.\n\nAfter the user understands the workflow that starts from having\nA-B and with clean working tree, IOW, your steps 2 through 5,\nmanaging the situation where you have that dirty state C* comes\nas a very natural extension of what he already knows, and at\nthat point, it does not matter to your use of stash/unstash what\nyou do between steps 2-5. You stash because you are going to do\nanything complicated, and the details of that complicated stuff\ndoes not matter why surrounding that sequence with stash/unstash\npair is useful. In yet another words, the pair of steps 1 and 6\nand the rest are orthogonal issues.\n\nSo what I would want to see in this example, if you wanted to\ntalk about the way git-stash can be used in conjunction with\ngit-rebase, would be something like this:\n\n-- clipcrop -- >8 -- clipcrop --\n\nEXAMPLE 1\n~~~~~~~~~\n\nSuppose you're tracking upstream development and developing a serarate\nfeature that is not yet ready. You started when upsream's HEAD was at\nE. You have progressed by 2 commits to (A,B).\n\nBecause your work A and B have some interactions to what has\nbeen done at the upstream in the meantime, you decide to update\nthe upstream code in order to make sure you don't diverge too\nfar.\n\n------------\n1. git checkout master # switch to master, where upstream code is\n2. git pull # update master to: D-E + F-G (new changes)\n3. git checkout topic # return to previous branch\n4. git rebase master # change branch from D-E-A-B to D-E-F-G-A'-B'\n\n A---B [3] A'--B' [4]\n / /\n master D---E [1] ---------- F---G [2]\n------------\n\nThe command at step 4 `git-rebase master topic` is just a short-hand\nof `git checkout topic` followed by `git rebase master`. When\nyou are done, your topic branch has two commits on top of the\nupdated master.\n\nNote, that If D and E does not have any interaction with what\nyour topic are attempting to achieve, there is no reason to\nrebase, but some people prefer it because rebasing tends to keep\nthe history clearer.\n\nIf you are in the middle of building some more stuff on top of\nB but not committed yet, rebase will refuse to run. You can use\ngitlink:git-stash[1] to help you in such a case.\n\n------------\n0. git stash\n1...4 (the same as before)\n5. git stash apply\n\n A---B---C* [0] A'--B'--C*\n / /\n master D---E [1] ---------- F---G [2]\n------------\n\nWhat happens to A, B, D, E, F and G is exactly the same as\nbefore. The only difference is that your work-in-progress\n(depicted as `C*` in the above, the work you did since `B`) is\nsaved away first, and then reapplied on top of updated `B`.\n\nIn short, the above procedure would transform this history\nstructure:\n\n------------\n A---B---C* topic\n /\n D---E---F---G* master\n------------\n\ninto this:\n\n------------\n A'--B'--C' topic\n /\n D---E---F---G master\n------------\n"}]}