{"thread":{"id":"25935","subject":"[PATCH] git-pull.txt: Add picture to --rebase option","startedAt":"2010-12-03T08:41:09Z","lastAt":"2010-12-03T19:35:38Z","messageCount":3,"participants":["jari.aalto@cante.net","Jakub Narebski","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"157183","messageId":"1291365669-10439-1-git-send-email-jari.aalto@cante.net","threadId":"25935","inReplyTo":null,"subject":"[PATCH] git-pull.txt: Add picture to --rebase option","fromName":"","fromEmail":"jari.aalto@cante.net","sentAt":"2010-12-03T08:41:09Z","receivedAt":"2010-12-03T08:41:09Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"From: Jari Aalto \n\nIllustrate what are the effects of the the option.\n\nSigned-off-by: Jari Aalto \n---\n Documentation/git-pull.txt | 12 ++++++++++++\n 1 files changed, 12 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\nindex e47361f..25eb6de 100644\n--- a/Documentation/git-pull.txt\n+++ b/Documentation/git-pull.txt\n@@ -106,6 +106,18 @@ This is a potentially _dangerous_ mode of operation.\n It rewrites history, which does not bode well when you\n published that history already. Do *not* use this option\n unless you have read linkgit:git-rebase[1] carefully.\n++\n+The effects of this option are:\n+------------\n+ [initial]\n+ o---o---o---A--B Your work in commit A and B\n+\n+ [git pull --rebase]\n+ o---o---o---*---*--A--B\n+ | |\n+ New updates merged in. Your work is rebased\n+ on top of them.\n+------------\n \n --no-rebase::\n \tOverride earlier --rebase.\n-- \n1.7.2.3\n"},{"id":"157210","messageId":"m3oc923nyz.fsf@localhost.localdomain","threadId":"25935","inReplyTo":"1291365669-10439-1-git-send-email-jari.aalto@cante.net","subject":"Re: [PATCH] git-pull.txt: Add picture to --rebase option","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2010-12-03T14:56:24Z","receivedAt":"2010-12-03T14:56:24Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"jari.aalto@cante.net writes:\n\n> From: Jari Aalto \n> \n> Illustrate what are the effects of the the option.\n> \n> Signed-off-by: Jari Aalto \n\n> ++\n> +The effects of this option are:\n> +------------\n> + [initial]\n> + o---o---o---A--B Your work in commit A and B\n> +\n> + [git pull --rebase]\n> + o---o---o---*---*--A--B\n> + | |\n> + New updates merged in. Your work is rebased\n> + on top of them.\n> +------------\n\nGood idea. Thanks.\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"157246","messageId":"7v62vaps39.fsf@alter.siamese.dyndns.org","threadId":"25935","inReplyTo":"1291365669-10439-1-git-send-email-jari.aalto@cante.net","subject":"Re: [PATCH] git-pull.txt: Add picture to --rebase option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-12-03T19:35:38Z","receivedAt":"2010-12-03T19:35:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"jari.aalto@cante.net writes:\n\n> From: Jari Aalto \n>\n> Illustrate what are the effects of the the option.\n>\n> Signed-off-by: Jari Aalto \n> ---\n> Documentation/git-pull.txt | 12 ++++++++++++\n> 1 files changed, 12 insertions(+), 0 deletions(-)\n>\n> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\n> index e47361f..25eb6de 100644\n> --- a/Documentation/git-pull.txt\n> +++ b/Documentation/git-pull.txt\n> @@ -106,6 +106,18 @@ This is a potentially _dangerous_ mode of operation.\n> It rewrites history, which does not bode well when you\n> published that history already. Do *not* use this option\n> unless you have read linkgit:git-rebase[1] carefully.\n> ++\n> +The effects of this option are:\n> +------------\n> + [initial]\n> + o---o---o---A--B Your work in commit A and B\n> +\n> + [git pull --rebase]\n> + o---o---o---*---*--A--B\n> + | |\n> + New updates merged in. Your work is rebased\n> + on top of them.\n> +------------\n\nWhile I think it is a good idea to have an illustration for pull-rebase, I\nam not happy with the above drawing.\n\nAn obvious nit is the wording \"merged in\", but more importantly, the\nreader won't be told three important facts about what you are trying to\nillustrate:\n\n - how these two '*' originally happened;\n - how they are preserved across the operation; as opposed to\n - how your own A and B are rewritten.\n\nAlso I do not think it is necessary to introduce an initial state separate\nfrom the one we already have established earlier in the documentation;\nit will reduce the mental burden of the readers if we set the stage only\nonce, and show two different outcomes starting from that same state.\n\nIt would be better to add something like the following after the first\nillustration on the page that shows how the default `git pull`\nconsolidates the histories by creating a merge commit `H`, immediately\nafter \"See linkgit:git-merge[1] for details,...\".\n\n [NOTE] \n The command can also be told to consolidate your work on top of what\n the other side did by rebasing, instead of merging, with `git pull\n --rebase`. Starting from the same state as illustrated above, it\n would create a new history like the following picture by rewriting\n your commits F and G to sit on top of the history the other side\n created:\n\n A---B---C master on origin\n / \\\n D---E---F---G F'--G' master\n\n Your original commits F and G are abandoned to be garbage collected,\n and your `master` branch will point at the tip of the rewritten\n history.\n\nNote that I did *NOT* run AsciiDoc on the above---this is not a suggestion\non formatting, but on the contents.\n"}]}