{"thread":{"id":"38499","subject":"Advice on edits to git-rebase man page","startedAt":"2015-02-04T20:21:14Z","lastAt":"2015-02-23T18:24:25Z","messageCount":7,"participants":["Matthew Brett","Matthieu Moy","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"255610","messageId":"CAH6Pt5pN8nrZzW+JntU5AWS1P4vu_JmdQBM_oR4Rfnh937wFPQ@mail.gmail.com","threadId":"38499","inReplyTo":null,"subject":"Advice on edits to git-rebase man page","fromName":"Matthew Brett","fromEmail":"matthew.brett@gmail.com","sentAt":"2015-02-04T20:21:14Z","receivedAt":"2015-02-04T20:21:14Z","isPatch":false,"sender":{"key":"matthew.brett@gmail.com","avatar":"https://gravatar.com/avatar/6ed344c0ea866123b1d564cfefafad9d405397fbb2bff9364f243c73aea0c74e?d=mp&s=160"},"body":"Hi,\n\nSorry for the rather open-ended email, but I am interested to whether\nyou would be interested in patches for git-rebase man page, based on a\ntutorial page I wrote some ago:\n\nhttp://matthew-brett.github.io/pydagogue/rebase_without_tears.html\n\nThe reason I ask, is because I have found the git-rebase man page\nparticularly difficult to read for an overview of what it is intended\nfor. A colleague recently wrote to me asking if I would consider\nproposing merging my page with the git man page.\n\nObviously my page as it is now is very different in tone from the\ngit-rebase page, but I think there are some aspects that could be\nfruitfully merged. Would you be interested in patches of this sort,\nor does the page seem too far from the intention of the man page?\n\nBest,\n\nMatthew\n"},{"id":"255623","messageId":"vpqa90s4oz2.fsf@anie.imag.fr","threadId":"38499","inReplyTo":"CAH6Pt5pN8nrZzW+JntU5AWS1P4vu_JmdQBM_oR4Rfnh937wFPQ@mail.gmail.com","subject":"Re: Advice on edits to git-rebase man page","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2015-02-05T10:44:33Z","receivedAt":"2015-02-05T10:44:33Z","isPatch":false,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Matthew Brett writes:\n\n> Obviously my page as it is now is very different in tone from the\n> git-rebase page, but I think there are some aspects that could be\n> fruitfully merged. Would you be interested in patches of this sort,\n> or does the page seem too far from the intention of the man page?\n\nI think it is deliberate that manpages are not written as tutorial, but\nas more advanced technical documentation. Just like learning Unix can\nhardly be done by reading \"man ls\", \"man cd\", ... the best entry point\nto learn Git is not the manpages. OTOH, I usually like Git's manpages\nwhen I know what I'm looking for.\n\nAll that being said, there's a lot of room for improvement in our\nmanpages, event remaining in a technical-style. I'm not a good juge\nbecause I already learnt how rebase works long ago, but the git rebase\nman page does seem terrible for bare mortals:\n\n NAME\n git-rebase - Forward-port local commits to the updated upstream head\n\n=> Quite technical already.\n\n DESCRIPTION\n If is specified, git rebase will perform an automatic\n git checkout before doing anything else. Otherwise it\n remains on the current branch.\n\n=> Ouch, do we really want to start a documentation like this?\n\nSo, the DESCRIPTION part can definitely be improved IMHO. Your notation\n, and may be an improvement\nalready.\n\nSome concrete examples may help too, like \"I started developing against\norigin/foo, on local branch bar, and now want to rebase my work on top\nof origin/boz\".\n\nMy 2 cents,\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"255635","messageId":"xmqqa90smbhu.fsf@gitster.dls.corp.google.com","threadId":"38499","inReplyTo":"vpqa90s4oz2.fsf@anie.imag.fr","subject":"Re: Advice on edits to git-rebase man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-02-05T18:58:21Z","receivedAt":"2015-02-05T18:58:21Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy writes:\n\n> NAME\n> git-rebase - Forward-port local commits to the updated upstream head\n>\n> => Quite technical already.\n\nVery much true, and I would say the description is \"technically\ncorrect\" in the sense that \"it is not wrong per-se\". There are a\nfew points that this fails to state and some that this overspecifies.\n\n - Rebase is about changing the base of an existing branch, but the\n description does not even mention the word \"branch\" [*1*].\n\n - There is nothing \"forward\" about it. I often see myself applying\n (tentatively) incoming patches on top of whatever commit I happen\n to have checked out, review it and then rebasing it to apply to\n older maintenance track if the topic is about fixing an old bug.\n\n - There is no point stressing \"local\" commits; all the operations\n you do to munge commits are local.\n\nPerhaps something like this instead?\n\n git-rebase - Rebuild a branch on top of a different commit\n\n\n> DESCRIPTION\n> If is specified, git rebase will perform an automatic\n> git checkout before doing anything else. Otherwise it\n> remains on the current branch.\n>\n> => Ouch, do we really want to start a documentation like this?\n\nNo. We should say what the command does and what the command is for\nin more general terms first and then describe how arguments can be\nused to affect it.\n\n> So, the DESCRIPTION part can definitely be improved IMHO. Your notation\n> , and may be an improvement\n> already.\n\n, and aren't technically\nwrong per-se, but I do not think bulk-replacing the words currently\nused in the manual page with these is an improvement at all, unless\nthe mental picture the explanation draws is also updated to match\nthese new words.\n\nreBASE is about changing the base of the affected branch, and the\nmental picture the current documentation draws is \"there is a plant,\nfrom which you cut a branch, scion. Then you graft the scion onto\nunderstock\". It calls the original tree (that the branch being\ntransplanted is part of) the \"old-base\", and the understock (that\nthe scion is going to be grafted onto) the \"new-base\". The word\n\"graft\" in \"graft point\" may better convey that we are doing a\ntransplanting than the current wording, but the word \"point\" makes\nit unclear to the readers if it refers to the \"point\" where the\nscion was cut from or where it is going to transplanted to, I am\nafraid.\n\nAlso and is probably too operational,\nand describing the command with only these two words would miss the\npoint that the command is about transplanting a branch. It is true\nthat in order to transplant a branch, you first need to figure out\nthe set of commits whose effects are to be replayed, you would need\n.. range computation, but it is an\nlower-level implemention detail.\n\n> Some concrete examples may help too, like \"I started developing against\n> origin/foo, on local branch bar, and now want to rebase my work on top\n> of origin/boz\".\n\nVery much so, but I wonder if it would be better to just refer to\nexamples in the tutorial (and if we do not have good examples there,\nwe should add some).\n\n[Footnote]\n\n *1* Yes, \"git rebase $newbase $commit^0\" form can be used to\n transplant a part of history leading to the $commit that does\n not sit at the tip of a branch (nor repoint a branch to point\n at the result at the end) as if $commit^0 were at the tip of\n some branch, but the key word here is \"as if\". The user is\n allowed to use the command pretending something that is not a\n branch is a branch, but what it tells us is that the command\n *is* about a branch.\n"},{"id":"255660","messageId":"vpq1tm412dk.fsf@anie.imag.fr","threadId":"38499","inReplyTo":"xmqqa90smbhu.fsf@gitster.dls.corp.google.com","subject":"Re: Advice on edits to git-rebase man page","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2015-02-05T21:20:55Z","receivedAt":"2015-02-05T21:20:55Z","isPatch":false,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Junio C Hamano writes:\n\n> Perhaps something like this instead?\n>\n> git-rebase - Rebuild a branch on top of a different commit\n\nI would say \"Replay history on top of a different commit\" instead.\n\"Rebuild\" may be misleading (it's not \"build\" as in \"compile & link\"),\nand the rebased history does not technically have to be a branch.\n\nBut both are far better than what we have IMHO.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"255662","messageId":"xmqqmw4sjbcm.fsf@gitster.dls.corp.google.com","threadId":"38499","inReplyTo":"vpq1tm412dk.fsf@anie.imag.fr","subject":"Re: Advice on edits to git-rebase man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-02-05T21:29:45Z","receivedAt":"2015-02-05T21:29:45Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy writes:\n\n> Junio C Hamano writes:\n>\n>> Perhaps something like this instead?\n>>\n>> git-rebase - Rebuild a branch on top of a different commit\n>\n> I would say \"Replay history on top of a different commit\" instead.\n> \"Rebuild\" may be misleading (it's not \"build\" as in \"compile & link\"),\n> and the rebased history does not technically have to be a branch.\n\nI am fine if the description were \"replay history and repoint the\nbranch tip to the result\"; the fact that branch tip moves is an\nimportant part of the semantics of the command.\n\nOtherwise, you cannot cleanly capture why we have rebase and\ncherry-pick (which can do ranges these days).\n"},{"id":"256295","messageId":"CAH6Pt5q91aEF4X=RTBV8BMHHf7vuiaikn9PT42UAe3Ht6hLr3A@mail.gmail.com","threadId":"38499","inReplyTo":"xmqqa90smbhu.fsf@gitster.dls.corp.google.com","subject":"Re: Advice on edits to git-rebase man page","fromName":"Matthew Brett","fromEmail":"matthew.brett@gmail.com","sentAt":"2015-02-18T18:59:33Z","receivedAt":"2015-02-18T18:59:33Z","isPatch":false,"sender":{"key":"matthew.brett@gmail.com","avatar":"https://gravatar.com/avatar/6ed344c0ea866123b1d564cfefafad9d405397fbb2bff9364f243c73aea0c74e?d=mp&s=160"},"body":"On Thu, Feb 5, 2015 at 10:58 AM, Junio C Hamano wrote:\n> Matthieu Moy writes:\n>\n>> NAME\n>> git-rebase - Forward-port local commits to the updated upstream head\n>>\n>> => Quite technical already.\n>\n> Very much true, and I would say the description is \"technically\n> correct\" in the sense that \"it is not wrong per-se\". There are a\n> few points that this fails to state and some that this overspecifies.\n>\n> - Rebase is about changing the base of an existing branch, but the\n> description does not even mention the word \"branch\" [*1*].\n>\n> - There is nothing \"forward\" about it. I often see myself applying\n> (tentatively) incoming patches on top of whatever commit I happen\n> to have checked out, review it and then rebasing it to apply to\n> older maintenance track if the topic is about fixing an old bug.\n>\n> - There is no point stressing \"local\" commits; all the operations\n> you do to munge commits are local.\n>\n> Perhaps something like this instead?\n>\n> git-rebase - Rebuild a branch on top of a different commit\n>\n>\n>> DESCRIPTION\n>> If is specified, git rebase will perform an automatic\n>> git checkout before doing anything else. Otherwise it\n>> remains on the current branch.\n>>\n>> => Ouch, do we really want to start a documentation like this?\n>\n> No. We should say what the command does and what the command is for\n> in more general terms first and then describe how arguments can be\n> used to affect it.\n>\n>> So, the DESCRIPTION part can definitely be improved IMHO. Your notation\n>> , and may be an improvement\n>> already.\n>\n> , and aren't technically\n> wrong per-se, but I do not think bulk-replacing the words currently\n> used in the manual page with these is an improvement at all, unless\n> the mental picture the explanation draws is also updated to match\n> these new words.\n>\n> reBASE is about changing the base of the affected branch, and the\n> mental picture the current documentation draws is \"there is a plant,\n> from which you cut a branch, scion. Then you graft the scion onto\n> understock\". It calls the original tree (that the branch being\n> transplanted is part of) the \"old-base\", and the understock (that\n> the scion is going to be grafted onto) the \"new-base\". The word\n> \"graft\" in \"graft point\" may better convey that we are doing a\n> transplanting than the current wording, but the word \"point\" makes\n> it unclear to the readers if it refers to the \"point\" where the\n> scion was cut from or where it is going to transplanted to, I am\n> afraid.\n\nThanks for the detailed feedback, sorry to be slow to reply.\n\nFor 'graft-point' - I agree that it is not immediately clear whether\nthis is the start of the commits that will be moved or the place that\nthey will be moved to. and are really not too bad\nin the current docs. After all, the command is called reBASE. On the\nother hand, the term 'graft' gives the impression of moving part of a\ntree from one origin (base) to another, which I think is correct,\nwhereas the 'base' terminology doesn't allow an obvious name for the\n'shoot' or 'scion'. For example, I don't think there is such a term\nin the current docs, other than 'set of commits'.\n\n> Also and is probably too operational,\n> and describing the command with only these two words would miss the\n> point that the command is about transplanting a branch. It is true\n> that in order to transplant a branch, you first need to figure out\n> the set of commits whose effects are to be replayed, you would need\n> .. range computation, but it is an\n> lower-level implemention detail.\n\nFirst - the current docs have for and\n for . I find both of these confusing and hard\nto read:\n\n* upstream - it isn't part of the semantics of rebase that the exclude\npoint should be something \"upstream\", that is only one of the common\nuses. I think this is related to the point you made about \"forward\"\nin the one-line description.\n* branch - too generic - does not convey the point that this is the\nincluded end point of the selected history.\n\nSecond - I don't understand why the actual use of and\n for selecting commits is a lower-level implementation detail.\nIs there some higher-level explanation for how these parameters select\nrevisions?\n\nThanks,\n\nMatthew\n"},{"id":"256526","messageId":"CAH6Pt5p=PvGDsWF3R+=qkhA=HBW6n6WjEZxRF0T7cQNhf4D9gw@mail.gmail.com","threadId":"38499","inReplyTo":"CAH6Pt5q91aEF4X=RTBV8BMHHf7vuiaikn9PT42UAe3Ht6hLr3A@mail.gmail.com","subject":"Re: Advice on edits to git-rebase man page","fromName":"Matthew Brett","fromEmail":"matthew.brett@gmail.com","sentAt":"2015-02-23T18:24:25Z","receivedAt":"2015-02-23T18:24:25Z","isPatch":false,"sender":{"key":"matthew.brett@gmail.com","avatar":"https://gravatar.com/avatar/6ed344c0ea866123b1d564cfefafad9d405397fbb2bff9364f243c73aea0c74e?d=mp&s=160"},"body":"On Wed, Feb 18, 2015 at 10:59 AM, Matthew Brett wrote:\n> On Thu, Feb 5, 2015 at 10:58 AM, Junio C Hamano wrote:\n>> Matthieu Moy writes:\n>>\n>>> NAME\n>>> git-rebase - Forward-port local commits to the updated upstream head\n>>>\n>>> => Quite technical already.\n>>\n>> Very much true, and I would say the description is \"technically\n>> correct\" in the sense that \"it is not wrong per-se\". There are a\n>> few points that this fails to state and some that this overspecifies.\n>>\n>> - Rebase is about changing the base of an existing branch, but the\n>> description does not even mention the word \"branch\" [*1*].\n>>\n>> - There is nothing \"forward\" about it. I often see myself applying\n>> (tentatively) incoming patches on top of whatever commit I happen\n>> to have checked out, review it and then rebasing it to apply to\n>> older maintenance track if the topic is about fixing an old bug.\n>>\n>> - There is no point stressing \"local\" commits; all the operations\n>> you do to munge commits are local.\n>>\n>> Perhaps something like this instead?\n>>\n>> git-rebase - Rebuild a branch on top of a different commit\n>>\n>>\n>>> DESCRIPTION\n>>> If is specified, git rebase will perform an automatic\n>>> git checkout before doing anything else. Otherwise it\n>>> remains on the current branch.\n>>>\n>>> => Ouch, do we really want to start a documentation like this?\n>>\n>> No. We should say what the command does and what the command is for\n>> in more general terms first and then describe how arguments can be\n>> used to affect it.\n>>\n>>> So, the DESCRIPTION part can definitely be improved IMHO. Your notation\n>>> , and may be an improvement\n>>> already.\n>>\n>> , and aren't technically\n>> wrong per-se, but I do not think bulk-replacing the words currently\n>> used in the manual page with these is an improvement at all, unless\n>> the mental picture the explanation draws is also updated to match\n>> these new words.\n>>\n>> reBASE is about changing the base of the affected branch, and the\n>> mental picture the current documentation draws is \"there is a plant,\n>> from which you cut a branch, scion. Then you graft the scion onto\n>> understock\". It calls the original tree (that the branch being\n>> transplanted is part of) the \"old-base\", and the understock (that\n>> the scion is going to be grafted onto) the \"new-base\". The word\n>> \"graft\" in \"graft point\" may better convey that we are doing a\n>> transplanting than the current wording, but the word \"point\" makes\n>> it unclear to the readers if it refers to the \"point\" where the\n>> scion was cut from or where it is going to transplanted to, I am\n>> afraid.\n>\n> Thanks for the detailed feedback, sorry to be slow to reply.\n>\n> For 'graft-point' - I agree that it is not immediately clear whether\n> this is the start of the commits that will be moved or the place that\n> they will be moved to. and are really not too bad\n> in the current docs. After all, the command is called reBASE. On the\n> other hand, the term 'graft' gives the impression of moving part of a\n> tree from one origin (base) to another, which I think is correct,\n> whereas the 'base' terminology doesn't allow an obvious name for the\n> 'shoot' or 'scion'. For example, I don't think there is such a term\n> in the current docs, other than 'set of commits'.\n>\n>> Also and is probably too operational,\n>> and describing the command with only these two words would miss the\n>> point that the command is about transplanting a branch. It is true\n>> that in order to transplant a branch, you first need to figure out\n>> the set of commits whose effects are to be replayed, you would need\n>> .. range computation, but it is an\n>> lower-level implemention detail.\n>\n> First - the current docs have for and\n> for . I find both of these confusing and hard\n> to read:\n>\n> * upstream - it isn't part of the semantics of rebase that the exclude\n> point should be something \"upstream\", that is only one of the common\n> uses. I think this is related to the point you made about \"forward\"\n> in the one-line description.\n> * branch - too generic - does not convey the point that this is the\n> included end point of the selected history.\n>\n> Second - I don't understand why the actual use of and\n> for selecting commits is a lower-level implementation detail.\n> Is there some higher-level explanation for how these parameters select\n> revisions?\n\nPerhaps this email was not well-directed, or there is not much\nappetite for a git-rebase rewrite at the moment. In any case, I'll\nunsubscribe for now, but if you think I can help, please do email me.\n\nCheers,\n\nMatthew\n"}]}