{"thread":{"id":"44382","subject":"[PATCH] Update git rebase documentation to clarify HEAD behavior","startedAt":"2016-10-27T06:24:50Z","lastAt":"2016-10-27T18:36:25Z","messageCount":3,"participants":["Cody Sehl","Junio C Hamano","Philip Oakley"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"304952","messageId":"010201580457bdd2-99237b54-5e36-4430-bb8d-7e9088aed522-000000@eu-west-1.amazonses.com","threadId":"44382","inReplyTo":null,"subject":"[PATCH] Update git rebase documentation to clarify HEAD behavior","fromName":"Cody Sehl","fromEmail":"cody.sehl@gmail.com","sentAt":"2016-10-27T04:13:28Z","receivedAt":"2016-10-27T06:24:50Z","isPatch":true,"sender":{"key":"cody.sehl@gmail.com","avatar":null},"body":"The first few paragraphs in the git-rebase.txt documentation lay out the steps git takes during a rebase:\n1. everything from `..HEAD` is saved to a temporary area\n2. `HEAD` is set to ``\n3. the changes held in the temporary area are applied one by one in order on top of the new `HEAD`\n\nThe second step was described using the phrase `The current branch is reset to `, which is true (because `HEAD` == current branch), but not clear.\n---\n Documentation/git-rebase.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex de222c8..c47ca11 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -33,7 +33,7 @@ of commits that would be shown by `git log ..HEAD`; or by\n description on `--fork-point` below); or by `git log HEAD`, if the\n `--root` option is specified.\n \n-The current branch is reset to , or if the\n+HEAD is reset to , or if the\n --onto option was supplied. This has the exact same effect as\n `git reset --hard ` (or ). ORIG_HEAD is set\n to point at the tip of the branch before the reset.\n\n--\nhttps://github.com/git/git/pull/301\n"},{"id":"304955","messageId":"xmqq8tta8f0x.fsf@gitster.mtv.corp.google.com","threadId":"44382","inReplyTo":"010201580457bdd2-99237b54-5e36-4430-bb8d-7e9088aed522-000000@eu-west-1.amazonses.com","subject":"Re: [PATCH] Update git rebase documentation to clarify HEAD behavior","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-10-27T06:47:10Z","receivedAt":"2016-10-27T06:47:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Cody Sehl writes:\n\n> The first few paragraphs in the git-rebase.txt documentation lay out the steps git takes during a rebase:\n> 1. everything from `..HEAD` is saved to a temporary area\n> 2. `HEAD` is set to ``\n> 3. the changes held in the temporary area are applied one by one in order on top of the new `HEAD`\n>\n> The second step was described using the phrase `The current branch is reset to `, which is true (because `HEAD` == current branch), but not clear.\n> ---\n\nPlease wrap your lines to reasonable lengths like 70 columns or so.\nPlease sign off your patch.\n\n> Documentation/git-rebase.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\n> index de222c8..c47ca11 100644\n> --- a/Documentation/git-rebase.txt\n> +++ b/Documentation/git-rebase.txt\n> @@ -33,7 +33,7 @@ of commits that would be shown by `git log ..HEAD`; or by\n> description on `--fork-point` below); or by `git log HEAD`, if the\n> `--root` option is specified.\n> \n> -The current branch is reset to , or if the\n> +HEAD is reset to , or if the\n> --onto option was supplied. This has the exact same effect as\n> `git reset --hard ` (or ). ORIG_HEAD is set\n> to point at the tip of the branch before the reset.\n\nThis is describing an ancient behaviour before 6fd2f5e60d (\"rebase:\noperate on a detached HEAD\", 2007-11-08) in v1.5.4 timeframe. We\napparently failed to update the description. \n\nThis depends on the desired technical detail of the description, but\na correct rewrite would be \"HEAD is detached at , or\n, and ORIG_HEAD is set to point at the tip of the branch\nbefore this happens\". Detaching the HEAD at no longer\nhas the same effect as \"git reset --hard \" (or ),\nso that sentence must go. It was the primary point of the ancient\nchange at 6fd2f5e60d after all.\n\nAnd then there is a new step (to be numbered 4. in your description\nin the proposed log message), which updates the tip of the branch to\nthe resulting HEAD (after replaying all these changes) and check the\nbranch out, which needs to be added. Perhaps after \"one by one, in\norder.\" Oh, the mention of \"reapplied to the current branch\" also\nneeds to be updated to \"reapplied to the detached HEAD\", too.\n\nOn the other hand, if we do not aim for that deep level of technical\ncorrectness, but want to tell a white lie to make it easier to\nunderstand at the conceptual level to new readers who haven't\ngrasped the detached HEAD, then the current description is fine. By\nbringing up \"HEAD\", you seem to be aiming for techincal correctness\n(which I tend to agree is a good direction to go in this part of the\ndocumentation), so the existing text needs a bit more work than your\npatch to be brought to the modern world.\n\n\n"},{"id":"304978","messageId":"1EBA3205AB8B43A3BBC48C701191520E@PhilipOakley","threadId":"44382","inReplyTo":"xmqq8tta8f0x.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] Update git rebase documentation to clarify HEAD behavior","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-10-27T14:06:55Z","receivedAt":"2016-10-27T18:36:25Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> Cody Sehl writes:\n>\n>> The first few paragraphs in the git-rebase.txt documentation lay out the \n>> steps git takes during a rebase:\n>> 1. everything from `..HEAD` is saved to a temporary area\n>> 2. `HEAD` is set to ``\n>> 3. the changes held in the temporary area are applied one by one in order \n>> on top of the new `HEAD`\n>>\n>> The second step was described using the phrase `The current branch is \n>> reset to `, which is true (because `HEAD` == current branch), \n>> but not clear.\n>> ---\n>\n> Please wrap your lines to reasonable lengths like 70 columns or so.\n> Please sign off your patch.\n>\n>> Documentation/git-rebase.txt | 2 +-\n>> 1 file changed, 1 insertion(+), 1 deletion(-)\n>>\n>> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\n>> index de222c8..c47ca11 100644\n>> --- a/Documentation/git-rebase.txt\n>> +++ b/Documentation/git-rebase.txt\n>> @@ -33,7 +33,7 @@ of commits that would be shown by `git log \n>> ..HEAD`; or by\n>> description on `--fork-point` below); or by `git log HEAD`, if the\n>> `--root` option is specified.\n>>\n>> -The current branch is reset to , or if the\n>> +HEAD is reset to , or if the\n>> --onto option was supplied. This has the exact same effect as\n>> `git reset --hard ` (or ). ORIG_HEAD is set\n>> to point at the tip of the branch before the reset.\n>\n> This is describing an ancient behaviour before 6fd2f5e60d (\"rebase:\n> operate on a detached HEAD\", 2007-11-08) in v1.5.4 timeframe. We\n> apparently failed to update the description.\n>\n> This depends on the desired technical detail of the description, but\n> a correct rewrite would be \"HEAD is detached at , or\n> , and ORIG_HEAD is set to point at the tip of the branch\n> before this happens\". Detaching the HEAD at no longer\n> has the same effect as \"git reset --hard \" (or ),\n> so that sentence must go. It was the primary point of the ancient\n> change at 6fd2f5e60d after all.\n>\n> And then there is a new step (to be numbered 4. in your description\n> in the proposed log message), which updates the tip of the branch to\n> the resulting HEAD (after replaying all these changes) and check the\n> branch out, which needs to be added. Perhaps after \"one by one, in\n> order.\" Oh, the mention of \"reapplied to the current branch\" also\n> needs to be updated to \"reapplied to the detached HEAD\", too.\n>\n> On the other hand, if we do not aim for that deep level of technical\n> correctness, but want to tell a white lie to make it easier to\n> understand at the conceptual level to new readers who haven't\n> grasped the detached HEAD, then the current description is fine. By\n> bringing up \"HEAD\", you seem to be aiming for techincal correctness\n> (which I tend to agree is a good direction to go in this part of the\n> documentation), so the existing text needs a bit more work than your\n> patch to be brought to the modern world.\n>\n\nA third option is to start with a short \"Conceptually, ..\" description which \ngives that summary overview, and then have a few \"In detail, ..\" paragraphs \nthat cover the ORIG_HEAD and Detatched HEAD, etc., that users should at \nleast be aware of (so they know they can come back and read the gory details \nwhen they need it;-)\n--\nPhilip \n\n"}]}