{"thread":{"id":"44224","subject":"[PATCH 2/6] Documentation/git-merge.txt: remove list of options from SYNOPSIS","startedAt":"2016-10-05T14:54:42Z","lastAt":"2016-10-07T13:13:57Z","messageCount":31,"participants":["sorganov@gmail.com","Jakub Narębski","Junio C Hamano","Jeff King","Sergey Organov"],"isPatch":true,"patchVersion":1,"patchTotal":6},"messages":[{"id":"303369","messageId":"fa4e150ab54f9a01b4b7ca496dfe514d5e106ff6.1475678515.git.sorganov@gmail.com","threadId":"44224","inReplyTo":"cover.1475678515.git.sorganov@gmail.com","subject":"[PATCH 2/6] Documentation/git-merge.txt: remove list of options from SYNOPSIS","fromName":"","fromEmail":"sorganov@gmail.com","sentAt":"2016-10-05T14:46:20Z","receivedAt":"2016-10-05T14:54:42Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"From: Sergey Organov <sorganov@gmail.com>\n\nThis partial list of option is confusing as it lacks a lot of\navailable options. It also clutters the SYNOPSIS making differences\nbetween forms of invocation less clear.\n\nSigned-off-by: Sergey Organov <sorganov@gmail.com>\n---\n Documentation/git-merge.txt | 5 +----\n 1 file changed, 1 insertion(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex b758d55..90342eb 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -9,10 +9,7 @@ git-merge - Join two or more development histories together\n SYNOPSIS\n --------\n [verse]\n-'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]\n-\t[-s <strategy>] [-X <strategy-option>] [-S[<keyid>]]\n-\t[--[no-]allow-unrelated-histories]\n-\t[--[no-]rerere-autoupdate] [-m <msg>] [<commit>...]\n+'git merge' [options] [-m <msg>] [<commit>...]\n 'git merge' <msg> HEAD <commit>...\n 'git merge' --abort\n \n-- \n2.10.0.1.g57b01a3\n\n"},{"id":"303370","messageId":"daa9f1869b6c35b1b74ee9b43c4862439af42483.1475678515.git.sorganov@gmail.com","threadId":"44224","inReplyTo":"cover.1475678515.git.sorganov@gmail.com","subject":"[PATCH 3/6] Documentation/git-merge.txt: fix SYNOPSIS of obsolete form to include options","fromName":"","fromEmail":"sorganov@gmail.com","sentAt":"2016-10-05T14:46:21Z","receivedAt":"2016-10-05T14:54:59Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"From: Sergey Organov <sorganov@gmail.com>\n\nSigned-off-by: Sergey Organov <sorganov@gmail.com>\n---\n Documentation/git-merge.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex 90342eb..216d2f4 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -10,7 +10,7 @@ SYNOPSIS\n --------\n [verse]\n 'git merge' [options] [-m <msg>] [<commit>...]\n-'git merge' <msg> HEAD <commit>...\n+'git merge' [options] <msg> HEAD <commit>...\n 'git merge' --abort\n \n DESCRIPTION\n-- \n2.10.0.1.g57b01a3\n\n"},{"id":"303371","messageId":"e74ae8afc1bfc4cd9161ccaa56d926a89439551e.1475678515.git.sorganov@gmail.com","threadId":"44224","inReplyTo":"cover.1475678515.git.sorganov@gmail.com","subject":"[PATCH 5/6] Documentation/git-merge.txt: improve short description in DESCRIPTION","fromName":"","fromEmail":"sorganov@gmail.com","sentAt":"2016-10-05T14:46:23Z","receivedAt":"2016-10-05T14:55:02Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"From: Sergey Organov <sorganov@gmail.com>\n\nOld description had a few problems:\n\n- sounded as if commits have changes\n\n- stated that changes are taken since some \"divergence point\"\n  that was not defined.\n\nNew description rather uses \"common ancestor\" and \"merge base\",\ndefinitions of which are easily discoverable in the rest of GIT\ndocumentation.\n\nSigned-off-by: Sergey Organov <sorganov@gmail.com>\n---\n Documentation/git-merge.txt | 25 +++++++++++++++----------\n 1 file changed, 15 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex cc0329d..351b8fc 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -16,11 +16,16 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Incorporates changes from the named commits (since the time their\n-histories diverged from the current branch) into the current\n-branch.  This command is used by 'git pull' to incorporate changes\n-from another repository and can be used by hand to merge changes\n-from one branch into another.\n+\n+Incorporates changes that lead to the named commits into the current\n+branch, and joins corresponding histories. The best common ancestor of\n+named commits and the current branch, called \"merge base\", is\n+calculated, and then net changes taken from the merge base to\n+the named commits are applied.\n+\n+This command is used by 'git pull' to incorporate changes from another\n+repository, and can be used by hand to merge changes from one branch\n+into another.\n \n Assume the following history exists and the current branch is\n \"`master`\":\n@@ -31,11 +36,11 @@ Assume the following history exists and the current branch is\n     D---E---F---G master\n ------------\n \n-Then \"`git merge topic`\" will replay the changes made on the\n-`topic` branch since it diverged from `master` (i.e., `E`) until\n-its current commit (`C`) on top of `master`, and record the result\n-in a new commit along with the names of the two parent commits and\n-a log message from the user describing the changes.\n+Then \"`git merge topic`\" will replay the changes made on the `topic`\n+branch since it diverged from `master` (i.e., `E`) until its current\n+commit (`C`) on top of `master`, and record the result in a new commit\n+along with references to the two parent commits and a log message from\n+the user describing the changes.\n \n ------------\n \t  A---B---C topic\n-- \n2.10.0.1.g57b01a3\n\n"},{"id":"303372","messageId":"773a11751c91c31a05c967ade902b0c8279aab56.1475678515.git.sorganov@gmail.com","threadId":"44224","inReplyTo":"cover.1475678515.git.sorganov@gmail.com","subject":"[PATCH 1/6] git-merge: clarify \"usage\" by adding \"-m <msg>\"","fromName":"","fromEmail":"sorganov@gmail.com","sentAt":"2016-10-05T14:46:19Z","receivedAt":"2016-10-05T14:55:03Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"From: Sergey Organov <sorganov@gmail.com>\n\n\"-m <msg>\" is one of essential distinctions between obsolete\ninvocation form and the recent one. Add it to the \"usage\" returned by\n'git merge -h' for more clarity.\n\nSigned-off-by: Sergey Organov <sorganov@gmail.com>\n---\n builtin/merge.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/builtin/merge.c b/builtin/merge.c\nindex a8b57c7..0e367ba 100644\n--- a/builtin/merge.c\n+++ b/builtin/merge.c\n@@ -43,7 +43,7 @@ struct strategy {\n };\n \n static const char * const builtin_merge_usage[] = {\n-\tN_(\"git merge [<options>] [<commit>...]\"),\n+\tN_(\"git merge [<options>] [-m <msg>] [<commit>...]\"),\n \tN_(\"git merge [<options>] <msg> HEAD <commit>\"),\n \tN_(\"git merge --abort\"),\n \tNULL\n-- \n2.10.0.1.g57b01a3\n\n"},{"id":"303373","messageId":"b91ef5e97c60a85cce1a13f88a19218fd0f05655.1475678515.git.sorganov@gmail.com","threadId":"44224","inReplyTo":"cover.1475678515.git.sorganov@gmail.com","subject":"[PATCH 6/6] Documentation/git-merge.txt: get rid of irrelevant references to git-pull","fromName":"","fromEmail":"sorganov@gmail.com","sentAt":"2016-10-05T14:46:24Z","receivedAt":"2016-10-05T14:55:05Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"From: Sergey Organov <sorganov@gmail.com>\n\nNo awareness of git-pull is required to understand git-merge operation,\nso leave reference to git-pull only where it actually makes sense, in\nthe description of fast-forward merges, and only as clarification of\nwhen this merging behaviour is mostly useful.\n\nOther references to git-pull are likely just a historical leftover\nthat are now neither required nor clarify anything. Besides, git-pull\nmay use rebase rather than merge, so it's also technically wrong to\nsay, unconditionally, that git-pull uses git-merge.\n\nOverall, let git-pull description refer to git-merge where\nappropriate, and not vice versa.\n\nSigned-off-by: Sergey Organov <sorganov@gmail.com>\n---\n Documentation/git-merge.txt | 36 ++++++++++++++++--------------------\n 1 file changed, 16 insertions(+), 20 deletions(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex 351b8fc..ba5fb0a 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -23,10 +23,6 @@ named commits and the current branch, called \"merge base\", is\n calculated, and then net changes taken from the merge base to\n the named commits are applied.\n \n-This command is used by 'git pull' to incorporate changes from another\n-repository, and can be used by hand to merge changes from one branch\n-into another.\n-\n Assume the following history exists and the current branch is\n \"`master`\":\n \n@@ -119,18 +115,17 @@ of `git fetch` for merging are merged to the current branch.\n PRE-MERGE CHECKS\n ----------------\n \n-Before applying outside changes, you should get your own work in\n-good shape and committed locally, so it will not be clobbered if\n-there are conflicts.  See also linkgit:git-stash[1].\n-'git pull' and 'git merge' will stop without doing anything when\n-local uncommitted changes overlap with files that 'git pull'/'git\n-merge' may need to update.\n+Before applying outside changes, you should get your own work in good\n+shape and committed locally, so it will not be clobbered if there are\n+conflicts. See also linkgit:git-stash[1]. 'git merge' will stop\n+without doing anything when local uncommitted changes overlap with\n+files that 'git merge' may need to update.\n \n-To avoid recording unrelated changes in the merge commit,\n-'git pull' and 'git merge' will also abort if there are any changes\n-registered in the index relative to the `HEAD` commit.  (One\n-exception is when the changed index entries are in the state that\n-would result from the merge already.)\n+To avoid recording unrelated changes in the merge commit, 'git merge'\n+will also abort if there are any changes registered in the index\n+relative to the `HEAD` commit. (One exception is when the changed\n+index entries are in the state that would result from the merge\n+already.)\n \n If all named commits are already ancestors of `HEAD`, 'git merge'\n will exit early with the message \"Already up-to-date.\"\n@@ -138,14 +133,15 @@ will exit early with the message \"Already up-to-date.\"\n FAST-FORWARD MERGE\n ------------------\n \n-Often the current branch head is an ancestor of the named commit.\n+Often the current branch head is an ancestor of the named commit.  In\n+this case, a new commit is not needed to store the combined history;\n+instead, the `HEAD` (along with the index) is updated to point at the\n+named commit, without creating an extra merge commit.\n+\n This is the most common case especially when invoked from 'git\n pull': you are tracking an upstream repository, you have committed\n no local changes, and now you want to update to a newer upstream\n-revision.  In this case, a new commit is not needed to store the\n-combined history; instead, the `HEAD` (along with the index) is\n-updated to point at the named commit, without creating an extra\n-merge commit.\n+revision.\n \n This behavior can be suppressed with the `--no-ff` option.\n \n-- \n2.10.0.1.g57b01a3\n\n"},{"id":"303374","messageId":"a33dd3ec3da0dc2dad72ed85edd29ff01f898831.1475678515.git.sorganov@gmail.com","threadId":"44224","inReplyTo":"cover.1475678515.git.sorganov@gmail.com","subject":"[PATCH 4/6] Documentation/git-merge.txt: improve short description in NAME","fromName":"","fromEmail":"sorganov@gmail.com","sentAt":"2016-10-05T14:46:22Z","receivedAt":"2016-10-05T14:55:06Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"From: Sergey Organov <sorganov@gmail.com>\n\nOld description not only raised the question of why the tool is called\ngit-merge rather than git-join, but \"join histories\" also sounds like\nvery simple operation, something like what \"git-merge -s ours\" does.\n\nSigned-off-by: Sergey Organov <sorganov@gmail.com>\n---\n Documentation/git-merge.txt | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex 216d2f4..cc0329d 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -3,7 +3,8 @@ git-merge(1)\n \n NAME\n ----\n-git-merge - Join two or more development histories together\n+\n+git-merge - Merge one or more branches to the current branch\n \n \n SYNOPSIS\n-- \n2.10.0.1.g57b01a3\n\n"},{"id":"303375","messageId":"cover.1475678515.git.sorganov@gmail.com","threadId":"44224","inReplyTo":null,"subject":"[PATCH 0/6] git-merge: a few documentation improvements","fromName":"","fromEmail":"sorganov@gmail.com","sentAt":"2016-10-05T14:46:18Z","receivedAt":"2016-10-05T14:55:07Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"From: Sergey Organov <sorganov@gmail.com>\n\nSergey Organov (6):\n  git-merge: clarify \"usage\" by adding \"-m <msg>\"\n  Documentation/git-merge.txt: remove list of options from SYNOPSIS\n  Documentation/git-merge.txt: fix SYNOPSIS of obsolete form to include\n    options\n  Documentation/git-merge.txt: improve short description in NAME\n  Documentation/git-merge.txt: improve short description in DESCRIPTION\n  Documentation/git-merge.txt: get rid of irrelevant references to\n    git-pull\n\n Documentation/git-merge.txt | 63 ++++++++++++++++++++++-----------------------\n builtin/merge.c             |  2 +-\n 2 files changed, 32 insertions(+), 33 deletions(-)\n\n-- \n2.10.0.1.g57b01a3\n\n"},{"id":"303390","messageId":"e03a84ad-9aa6-8ada-5828-7b28f76baaaf@gmail.com","threadId":"44224","inReplyTo":"e74ae8afc1bfc4cd9161ccaa56d926a89439551e.1475678515.git.sorganov@gmail.com","subject":"Re: [PATCH 5/6] Documentation/git-merge.txt: improve short description in DESCRIPTION","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2016-10-05T16:58:10Z","receivedAt":"2016-10-05T16:58:32Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"W dniu 05.10.2016 o 16:46, sorganov@gmail.com pisze:\n> From: Sergey Organov <sorganov@gmail.com>\n> \n> Old description had a few problems:\n> \n> - sounded as if commits have changes\n> \n> - stated that changes are taken since some \"divergence point\"\n>   that was not defined.\n> \n> New description rather uses \"common ancestor\" and \"merge base\",\n> definitions of which are easily discoverable in the rest of GIT\n> documentation.\n\nThis is a step in a good direction, but it has a few issues.\n\n> \n> Signed-off-by: Sergey Organov <sorganov@gmail.com>\n> ---\n>  Documentation/git-merge.txt | 25 +++++++++++++++----------\n>  1 file changed, 15 insertions(+), 10 deletions(-)\n> \n> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\n> index cc0329d..351b8fc 100644\n> --- a/Documentation/git-merge.txt\n> +++ b/Documentation/git-merge.txt\n> @@ -16,11 +16,16 @@ SYNOPSIS\n>  \n>  DESCRIPTION\n>  -----------\n> -Incorporates changes from the named commits (since the time their\n> -histories diverged from the current branch) into the current\n> -branch.  This command is used by 'git pull' to incorporate changes\n> -from another repository and can be used by hand to merge changes\n> -from one branch into another.\n> +\n> +Incorporates changes that lead to the named commits into the current\n> +branch, and joins corresponding histories. The best common ancestor of\n> +named commits and the current branch, called \"merge base\", is\n> +calculated, and then net changes taken from the merge base to\n> +the named commits are applied.\n\nThe first sentence is all right; it reads better than the original\nwithout the introduced part in parentheses.  The only minor issue\nis with \"joins corresponding histories\" - it is a good description,\nbut may imply that the branch we are merging vanishes: it doesn't.\nBut all in all, it is a good change.\n\nSecond sentence has some problems.  First, while it is a good idea\nto use well defined term \"merge base\", I think writing \"since the\ntime their histories diverged\" or \"(which is the point where histories\ndiverged)\" would be a good plain language description; it was removed\nentirely in the proposal.\n\nSecond, while \"common ancestor\" and \"least common ancestor\" are well\ndefined in mathematics of graphs, \"best common ancestor\" isn't...\nbut this is what git-merge-base(1) documentation uses.\n\nAlso, the \"best common ancestor\" doesn't need to be only one.  There\nmight be many such ancestors... though Git would generate then a\nvirtual best common ancestor thanks to recursive merge strategy.\nAnd usually there is only one \"best common ancestor\", that is a single\nmerge base.  So this may need clarification, but it is not much of\na problem.\n\nThird, and most important, is that \"net changes taken from the merge\nbase to the named commits are applied\" is simply not true.  The\n`git merge` command does not reapply changes - that is what rebase\nand cherry-pick do.  The merge operation uses 3-way merge strategy\n(diff3) between merge-base, current branch, and merged commit.\nThat is, it finds differences between differences, and \"applies\"\nthat.\n\nSee \"A Formal Investigation of Diff3\" paper by Sanjeev Khanna,\nKeshav Kunal, and Benjamin C. Pierce:\n  http://www.cis.upenn.edu/~bcpierce/papers/diff3-short.pdf\n\nI'm not sure how to explain it succintly.  Perhaps\n\n  net changes between merge base to the current (merged into)\n  branch and named commits are integrated\n\nThere is description of trivial 3-way merge somewhere in Git docs,\nthough in very unobvious place; we can link it.\n\n> +\n> +This command is used by 'git pull' to incorporate changes from another\n> +repository, and can be used by hand to merge changes from one branch\n> +into another.\n\nRather \"can be used by 'git pull'\", or \"is used by 'git pull' (unless\nconfigured otherwise)\"...\n\nSeparating this information makes a very good sense.  Thanks.\n\n>  \n>  Assume the following history exists and the current branch is\n>  \"`master`\":\n> @@ -31,11 +36,11 @@ Assume the following history exists and the current branch is\n>      D---E---F---G master\n>  ------------\n>  \n> -Then \"`git merge topic`\" will replay the changes made on the\n> -`topic` branch since it diverged from `master` (i.e., `E`) until\n> -its current commit (`C`) on top of `master`, and record the result\n> -in a new commit along with the names of the two parent commits and\n> -a log message from the user describing the changes.\n> +Then \"`git merge topic`\" will replay the changes made on the `topic`\n> +branch since it diverged from `master` (i.e., `E`) until its current\n> +commit (`C`) on top of `master`, and record the result in a new commit\n> +along with references to the two parent commits and a log message from\n> +the user describing the changes.\n\nWhat the happened here!?!  Please do not rewrap documentation, especially\nnot without changes!\n\n>  \n>  ------------\n>  \t  A---B---C topic\n> \n-- \nJakub Narębski\n\n"},{"id":"303413","messageId":"xmqqint6pu3b.fsf@gitster.mtv.corp.google.com","threadId":"44224","inReplyTo":"773a11751c91c31a05c967ade902b0c8279aab56.1475678515.git.sorganov@gmail.com","subject":"Re: [PATCH 1/6] git-merge: clarify \"usage\" by adding \"-m <msg>\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-10-05T17:46:16Z","receivedAt":"2016-10-05T17:47:04Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"sorganov@gmail.com writes:\n\n> From: Sergey Organov <sorganov@gmail.com>\n>\n> \"-m <msg>\" is one of essential distinctions between obsolete\n> invocation form and the recent one. Add it to the \"usage\" returned by\n> 'git merge -h' for more clarity.\n>\n> Signed-off-by: Sergey Organov <sorganov@gmail.com>\n> ---\n>  builtin/merge.c | 2 +-\n>  1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/builtin/merge.c b/builtin/merge.c\n> index a8b57c7..0e367ba 100644\n> --- a/builtin/merge.c\n> +++ b/builtin/merge.c\n> @@ -43,7 +43,7 @@ struct strategy {\n>  };\n>  \n>  static const char * const builtin_merge_usage[] = {\n> -\tN_(\"git merge [<options>] [<commit>...]\"),\n> +\tN_(\"git merge [<options>] [-m <msg>] [<commit>...]\"),\n>  \tN_(\"git merge [<options>] <msg> HEAD <commit>\"),\n>  \tN_(\"git merge --abort\"),\n>  \tNULL\n\nWhile this is not wrong per-se, as the deprecated form will go away\nsoon, I hope you do not mind if I had to drop this one from the\nseries to avoid merge conflicts to 'pu' (I do not know how bad the\nconflict would be yet; I am just reviewing in my MUA).\n\n"},{"id":"303414","messageId":"xmqqeg3upu0m.fsf@gitster.mtv.corp.google.com","threadId":"44224","inReplyTo":"fa4e150ab54f9a01b4b7ca496dfe514d5e106ff6.1475678515.git.sorganov@gmail.com","subject":"Re: [PATCH 2/6] Documentation/git-merge.txt: remove list of options from SYNOPSIS","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-10-05T17:47:53Z","receivedAt":"2016-10-05T17:48:02Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"sorganov@gmail.com writes:\n\n> From: Sergey Organov <sorganov@gmail.com>\n>\n> This partial list of option is confusing as it lacks a lot of\n> available options. It also clutters the SYNOPSIS making differences\n> between forms of invocation less clear.\n>\n> Signed-off-by: Sergey Organov <sorganov@gmail.com>\n> ---\n>  Documentation/git-merge.txt | 5 +----\n>  1 file changed, 1 insertion(+), 4 deletions(-)\n>\n> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\n> index b758d55..90342eb 100644\n> --- a/Documentation/git-merge.txt\n> +++ b/Documentation/git-merge.txt\n> @@ -9,10 +9,7 @@ git-merge - Join two or more development histories together\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]\n> -\t[-s <strategy>] [-X <strategy-option>] [-S[<keyid>]]\n> -\t[--[no-]allow-unrelated-histories]\n> -\t[--[no-]rerere-autoupdate] [-m <msg>] [<commit>...]\n> +'git merge' [options] [-m <msg>] [<commit>...]\n>  'git merge' <msg> HEAD <commit>...\n>  'git merge' --abort\n\nSame comment as 1/6; as we'd hopefully be removing the deprecated\nform soonish, it would probably make sense to leave only two, i.e.\n\n\tgit merge [options] [<commit>...]\n\tgit merge --abort\n\nin synposis.\n"},{"id":"303415","messageId":"xmqqa8eiptt2.fsf@gitster.mtv.corp.google.com","threadId":"44224","inReplyTo":"a33dd3ec3da0dc2dad72ed85edd29ff01f898831.1475678515.git.sorganov@gmail.com","subject":"Re: [PATCH 4/6] Documentation/git-merge.txt: improve short description in NAME","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-10-05T17:52:25Z","receivedAt":"2016-10-05T17:52:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"sorganov@gmail.com writes:\n\n> From: Sergey Organov <sorganov@gmail.com>\n>\n> Old description not only raised the question of why the tool is called\n> git-merge rather than git-join, but \"join histories\" also sounds like\n> very simple operation, something like what \"git-merge -s ours\" does.\n>\n> Signed-off-by: Sergey Organov <sorganov@gmail.com>\n> ---\n>  Documentation/git-merge.txt | 3 ++-\n>  1 file changed, 2 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\n> index 216d2f4..cc0329d 100644\n> --- a/Documentation/git-merge.txt\n> +++ b/Documentation/git-merge.txt\n> @@ -3,7 +3,8 @@ git-merge(1)\n>  \n>  NAME\n>  ----\n> -git-merge - Join two or more development histories together\n> +\n> +git-merge - Merge one or more branches to the current branch\n\nThis patch, evaluated by itself, looks like a regression in that it\ntries to explain \"merge\" by using verb \"merge\", making it fuzzier to\nthose who do not yet know what a \"merge\" is.  That was why it tried\nto explain \"merge\" as an operation to join histories.\n\nHowever, the next one, 5/6, resurrects the \"join history\" in the\ndescription part to help them, so the damage is not so severe when\nwe take them together.\n\nI haven't formed firm opinion on this patch yet.\n"},{"id":"303416","messageId":"20161005175512.aruzndaow3g2jmt7@sigill.intra.peff.net","threadId":"44224","inReplyTo":"a33dd3ec3da0dc2dad72ed85edd29ff01f898831.1475678515.git.sorganov@gmail.com","subject":"Re: [PATCH 4/6] Documentation/git-merge.txt: improve short description in NAME","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-10-05T17:55:13Z","receivedAt":"2016-10-05T17:55:19Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Oct 05, 2016 at 05:46:22PM +0300, sorganov@gmail.com wrote:\n\n> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\n> index 216d2f4..cc0329d 100644\n> --- a/Documentation/git-merge.txt\n> +++ b/Documentation/git-merge.txt\n> @@ -3,7 +3,8 @@ git-merge(1)\n>  \n>  NAME\n>  ----\n> -git-merge - Join two or more development histories together\n> +\n> +git-merge - Merge one or more branches to the current branch\n\nI wonder if we should be more clear that you don't have to merge a\nbranch; you can merge any commit. I do agree that the original was\nunnecessarily general. And I think \"the current branch\" is accurate\n(technically it can be to a detached HEAD, but that is pedantry that\ndoesn't need to make it into the synopsis).\n\nSo maybe \"Merge one or more commits into the current branch\".  I guess\nthat is a bit vague, too. It is really \"commit tips\" or \"lines of\ndevelopment\" that we are merging. Bringing them in of course brings in\nmany commits, but the \"or more\" there is meant to hint at multi-parent\nmerges.\n\nSo perhaps \"one or more branches\", while not completely accurate, is the\nbest we can do. I dunno.\n\n-Peff\n"},{"id":"303417","messageId":"xmqq60p6pt4k.fsf@gitster.mtv.corp.google.com","threadId":"44224","inReplyTo":"e74ae8afc1bfc4cd9161ccaa56d926a89439551e.1475678515.git.sorganov@gmail.com","subject":"Re: [PATCH 5/6] Documentation/git-merge.txt: improve short description in DESCRIPTION","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-10-05T18:07:07Z","receivedAt":"2016-10-05T18:07:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"sorganov@gmail.com writes:\n\n> From: Sergey Organov <sorganov@gmail.com>\n>\n> Old description had a few problems:\n>\n> - sounded as if commits have changes\n>\n> - stated that changes are taken since some \"divergence point\"\n>   that was not defined.\n>\n> New description rather uses \"common ancestor\" and \"merge base\",\n> definitions of which are easily discoverable in the rest of GIT\n> documentation.\n>\n> Signed-off-by: Sergey Organov <sorganov@gmail.com>\n> ---\n>  Documentation/git-merge.txt | 25 +++++++++++++++----------\n>  1 file changed, 15 insertions(+), 10 deletions(-)\n>\n> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\n> index cc0329d..351b8fc 100644\n> --- a/Documentation/git-merge.txt\n> +++ b/Documentation/git-merge.txt\n> @@ -16,11 +16,16 @@ SYNOPSIS\n>  \n>  DESCRIPTION\n>  -----------\n> -Incorporates changes from the named commits (since the time their\n> -histories diverged from the current branch) into the current\n> -branch.  This command is used by 'git pull' to incorporate changes\n> -from another repository and can be used by hand to merge changes\n> -from one branch into another.\n> +\n> +Incorporates changes that lead to the named commits into the current\n> +branch, and joins corresponding histories. The best common ancestor of\n> +named commits and the current branch, called \"merge base\", is\n> +calculated, and then net changes taken from the merge base to\n> +the named commits are applied.\n> +\n> +This command is used by 'git pull' to incorporate changes from another\n> +repository, and can be used by hand to merge changes from one branch\n> +into another.\n\nContent change together with re-flowing the text makes it more\ncostly than necessary to review a change like this.  Please avoid\ndoing so in your future patches.\n\nI like what the updated description says very much.  I however\nwonder if \"and can be used by hand...\" is still appropriate, or\nneeds a bit of modernizing.  It feels a bit awkward by making it\nsound as if 'git merge' is primarily an implementation detail of\n'git pull' but it can also be used as the first-class command, which\nused to be the case in the old days back when \"git pull . other\" was\nalso perfectly good way to merge the 'other' branch from your own\nrepository, but I think your update is meant to clarify that we no\nlonger live in that old world ;-)\n\n> @@ -31,11 +36,11 @@ Assume the following history exists and the current branch is\n>      D---E---F---G master\n>  ------------\n>  \n> -Then \"`git merge topic`\" will replay the changes made on the\n> -`topic` branch since it diverged from `master` (i.e., `E`) until\n> -its current commit (`C`) on top of `master`, and record the result\n> -in a new commit along with the names of the two parent commits and\n> -a log message from the user describing the changes.\n\n> -Then \"`git merge topic`\" will replay the changes made on the `topic`\n> -branch since it diverged from `master` (i.e., `E`) until its current\n> -commit (`C`) on top of `master`, and record the result in a new commit\n> -along with the names of the two parent commits and a log message from\n> -the user describing the changes.\n\n> +Then \"`git merge topic`\" will replay the changes made on the `topic`\n> +branch since it diverged from `master` (i.e., `E`) until its current\n> +commit (`C`) on top of `master`, and record the result in a new commit\n> +along with references to the two parent commits and a log message from\n> +the user describing the changes.\n\nContent change together with re-flowing the text makes it more\ncostly than necessary to review a change like this.  Please avoid\ndoing so in your future patches.\n\nI had to re-flow the original you removed to match how you flowed in\nthe updated one and stare at it for a while to spot that the only\nchange was to rephrase \"the names of the parents\" to \"references to\nthe parents\".  I do not know if the updated phrasing is better.  The\n\"name\" in the original was meant to be a short-hand for \"object name\",\nand I would support a change to spell it out to clarify; \"reference\"\ncan be a vague word that can mean different things in Git, and when\nthe word is given without context, most Git people would think that\nthe word refers to \"refs\", but that is definitely not what the new\ncommit records, so...\n"},{"id":"303422","messageId":"xmqqzimioc7s.fsf@gitster.mtv.corp.google.com","threadId":"44224","inReplyTo":"b91ef5e97c60a85cce1a13f88a19218fd0f05655.1475678515.git.sorganov@gmail.com","subject":"Re: [PATCH 6/6] Documentation/git-merge.txt: get rid of irrelevant references to git-pull","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-10-05T18:57:43Z","receivedAt":"2016-10-05T18:57:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"sorganov@gmail.com writes:\n\n> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\n> index 351b8fc..ba5fb0a 100644\n> --- a/Documentation/git-merge.txt\n> +++ b/Documentation/git-merge.txt\n> @@ -23,10 +23,6 @@ named commits and the current branch, called \"merge base\", is\n>  calculated, and then net changes taken from the merge base to\n>  the named commits are applied.\n>  \n> -This command is used by 'git pull' to incorporate changes from another\n> -repository, and can be used by hand to merge changes from one branch\n> -into another.\n> -\n\nGood.\n\n> @@ -119,18 +115,17 @@ of `git fetch` for merging are merged to the current branch.\n>  PRE-MERGE CHECKS\n>  ----------------\n>  \n> -Before applying outside changes, you should get your own work in\n> -good shape and committed locally, so it will not be clobbered if\n> -there are conflicts.  See also linkgit:git-stash[1].\n> -'git pull' and 'git merge' will stop without doing anything when\n> -local uncommitted changes overlap with files that 'git pull'/'git\n> -merge' may need to update.\n> +Before applying outside changes, you should get your own work in good\n> +shape and committed locally, so it will not be clobbered if there are\n> +conflicts. See also linkgit:git-stash[1]. 'git merge' will stop\n> +without doing anything when local uncommitted changes overlap with\n> +files that 'git merge' may need to update.\n>  \n> -To avoid recording unrelated changes in the merge commit,\n> -'git pull' and 'git merge' will also abort if there are any changes\n> -registered in the index relative to the `HEAD` commit.  (One\n> -exception is when the changed index entries are in the state that\n> -would result from the merge already.)\n> +To avoid recording unrelated changes in the merge commit, 'git merge'\n> +will also abort if there are any changes registered in the index\n> +relative to the `HEAD` commit. (One exception is when the changed\n> +index entries are in the state that would result from the merge\n> +already.)\n\nOK, so \"git pull and git merge\" have been updated to say \"git\nmerge\" and there is no other change.  Looks good.\n\nPlease do not re-flow and change in the same commit, by the way.\n\n> @@ -138,14 +133,15 @@ will exit early with the message \"Already up-to-date.\"\n>  FAST-FORWARD MERGE\n>  ------------------\n>  \n> -Often the current branch head is an ancestor of the named commit.\n> +Often the current branch head is an ancestor of the named commit.  In\n> +this case, a new commit is not needed to store the combined history;\n> +instead, the `HEAD` (along with the index) is updated to point at the\n> +named commit, without creating an extra merge commit.\n> +\n>  This is the most common case especially when invoked from 'git\n>  pull': you are tracking an upstream repository, you have committed\n>  no local changes, and now you want to update to a newer upstream\n> -revision.  In this case, a new commit is not needed to store the\n> -combined history; instead, the `HEAD` (along with the index) is\n> -updated to point at the named commit, without creating an extra\n> -merge commit.\n> +revision.\n\nI am not sure if the post-image of this hunk is better than the\noriginal.\n\n"},{"id":"303432","messageId":"xmqqr37uo99b.fsf@gitster.mtv.corp.google.com","threadId":"44224","inReplyTo":"e03a84ad-9aa6-8ada-5828-7b28f76baaaf@gmail.com","subject":"Re: [PATCH 5/6] Documentation/git-merge.txt: improve short description in DESCRIPTION","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-10-05T20:01:36Z","receivedAt":"2016-10-05T20:01:44Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jakub Narębski <jnareb@gmail.com> writes:\n\n>> +\n>> +This command is used by 'git pull' to incorporate changes from another\n>> +repository, and can be used by hand to merge changes from one branch\n>> +into another.\n>\n> Rather \"can be used by 'git pull'\", or \"is used by 'git pull' (unless\n> configured otherwise)\"...\n\nI think you are misreading the original and the update (see my\ncomments in the other message).\n\n>> @@ -31,11 +36,11 @@ Assume the following history exists and the current branch is\n>>      D---E---F---G master\n>>  ------------\n>>  \n>> -Then \"`git merge topic`\" will replay the changes made on the\n>> -`topic` branch since it diverged from `master` (i.e., `E`) until\n>> -its current commit (`C`) on top of `master`, and record the result\n>> -in a new commit along with the names of the two parent commits and\n>> -a log message from the user describing the changes.\n>> +Then \"`git merge topic`\" will replay the changes made on the `topic`\n>> +branch since it diverged from `master` (i.e., `E`) until its current\n>> +commit (`C`) on top of `master`, and record the result in a new commit\n>> +along with references to the two parent commits and a log message from\n>> +the user describing the changes.\n>\n> What the happened here!?!  Please do not rewrap documentation, especially\n> not without changes!\n\nYes, reflowing is bad but you can spot the change from \"along with\nthe names of the parent commits\" to \"along with references to the\nparent commits\" if you stare at it long enough ;-)\n\n"},{"id":"303435","messageId":"87k2dmr0j5.fsf@javad.com","threadId":"44224","inReplyTo":"xmqqint6pu3b.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH 1/6] git-merge: clarify \"usage\" by adding \"-m <msg>\"","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2016-10-05T20:41:50Z","receivedAt":"2016-10-05T20:49:40Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> sorganov@gmail.com writes:\n>\n>> From: Sergey Organov <sorganov@gmail.com>\n>>\n>> \"-m <msg>\" is one of essential distinctions between obsolete\n>> invocation form and the recent one. Add it to the \"usage\" returned by\n>> 'git merge -h' for more clarity.\n>>\n>> Signed-off-by: Sergey Organov <sorganov@gmail.com>\n>> ---\n>>  builtin/merge.c | 2 +-\n>>  1 file changed, 1 insertion(+), 1 deletion(-)\n>>\n>> diff --git a/builtin/merge.c b/builtin/merge.c\n>> index a8b57c7..0e367ba 100644\n>> --- a/builtin/merge.c\n>> +++ b/builtin/merge.c\n>> @@ -43,7 +43,7 @@ struct strategy {\n>>  };\n>>  \n>>  static const char * const builtin_merge_usage[] = {\n>> -\tN_(\"git merge [<options>] [<commit>...]\"),\n>> +\tN_(\"git merge [<options>] [-m <msg>] [<commit>...]\"),\n>>  \tN_(\"git merge [<options>] <msg> HEAD <commit>\"),\n>>  \tN_(\"git merge --abort\"),\n>>  \tNULL\n>\n> While this is not wrong per-se, as the deprecated form will go away\n> soon, I hope you do not mind if I had to drop this one from the\n> series to avoid merge conflicts to 'pu' (I do not know how bad the\n> conflict would be yet; I am just reviewing in my MUA).\n\nYeah, sure. I was not aware obsolete form description is to go away\nsoon.\n"},{"id":"303436","messageId":"87fuoar0eb.fsf@javad.com","threadId":"44224","inReplyTo":"20161005175512.aruzndaow3g2jmt7@sigill.intra.peff.net","subject":"Re: [PATCH 4/6] Documentation/git-merge.txt: improve short description in NAME","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2016-10-05T20:44:44Z","receivedAt":"2016-10-05T20:54:40Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n> On Wed, Oct 05, 2016 at 05:46:22PM +0300, sorganov@gmail.com wrote:\n>\n>> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\n>> index 216d2f4..cc0329d 100644\n>> --- a/Documentation/git-merge.txt\n>> +++ b/Documentation/git-merge.txt\n>> @@ -3,7 +3,8 @@ git-merge(1)\n>>  \n>>  NAME\n>>  ----\n>> -git-merge - Join two or more development histories together\n>> +\n>> +git-merge - Merge one or more branches to the current branch\n>\n> I wonder if we should be more clear that you don't have to merge a\n> branch; you can merge any commit. I do agree that the original was\n> unnecessarily general. And I think \"the current branch\" is accurate\n> (technically it can be to a detached HEAD, but that is pedantry that\n> doesn't need to make it into the synopsis).\n>\n> So maybe \"Merge one or more commits into the current branch\".  I guess\n> that is a bit vague, too. It is really \"commit tips\" or \"lines of\n> development\" that we are merging. Bringing them in of course brings in\n> many commits, but the \"or more\" there is meant to hint at multi-parent\n> merges.\n>\n> So perhaps \"one or more branches\", while not completely accurate, is the\n> best we can do. I dunno.\n\nYou've basically repeated my entire line of thinking that lead to the\npatch.\n\n-- Sergey.\n"},{"id":"303438","messageId":"87a8eiqzlk.fsf@javad.com","threadId":"44224","inReplyTo":"xmqqa8eiptt2.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH 4/6] Documentation/git-merge.txt: improve short description in NAME","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2016-10-05T21:01:59Z","receivedAt":"2016-10-05T21:02:33Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> sorganov@gmail.com writes:\n>\n>> From: Sergey Organov <sorganov@gmail.com>\n>>\n>> Old description not only raised the question of why the tool is called\n>> git-merge rather than git-join, but \"join histories\" also sounds like\n>> very simple operation, something like what \"git-merge -s ours\" does.\n>>\n>> Signed-off-by: Sergey Organov <sorganov@gmail.com>\n>> ---\n>>  Documentation/git-merge.txt | 3 ++-\n>>  1 file changed, 2 insertions(+), 1 deletion(-)\n>>\n>> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\n>> index 216d2f4..cc0329d 100644\n>> --- a/Documentation/git-merge.txt\n>> +++ b/Documentation/git-merge.txt\n>> @@ -3,7 +3,8 @@ git-merge(1)\n>>  \n>>  NAME\n>>  ----\n>> -git-merge - Join two or more development histories together\n>> +\n>> +git-merge - Merge one or more branches to the current branch\n>\n> This patch, evaluated by itself, looks like a regression in that it\n> tries to explain \"merge\" by using verb \"merge\", making it fuzzier to\n> those who do not yet know what a \"merge\" is.  That was why it tried\n> to explain \"merge\" as an operation to join histories.\n\nMy thought was that \"merge\", the operation, is so well-known term that\nit could well go into the NAME section without explanation.\n\nBesides:\n\n$ man merge\nNAME\n       merge - three-way file merge\n[...]\n\nUses the same pattern.\n\n>\n> However, the next one, 5/6, resurrects the \"join history\" in the\n> description part to help them, so the damage is not so severe when\n> we take them together.\n\nDamage? In SCM world we can track the issue back to:\n\n$ man -k rcsmerge\nrcsmerge (1)         - merge RCS revisions\n\n-- Sergey\n"},{"id":"303439","messageId":"8760p6qzjl.fsf@javad.com","threadId":"44224","inReplyTo":"xmqqeg3upu0m.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH 2/6] Documentation/git-merge.txt: remove list of options from SYNOPSIS","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2016-10-05T21:03:10Z","receivedAt":"2016-10-05T21:03:17Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> sorganov@gmail.com writes:\n>\n>> From: Sergey Organov <sorganov@gmail.com>\n>>\n>> This partial list of option is confusing as it lacks a lot of\n>> available options. It also clutters the SYNOPSIS making differences\n>> between forms of invocation less clear.\n>>\n>> Signed-off-by: Sergey Organov <sorganov@gmail.com>\n>> ---\n>>  Documentation/git-merge.txt | 5 +----\n>>  1 file changed, 1 insertion(+), 4 deletions(-)\n>>\n>> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\n>> index b758d55..90342eb 100644\n>> --- a/Documentation/git-merge.txt\n>> +++ b/Documentation/git-merge.txt\n>> @@ -9,10 +9,7 @@ git-merge - Join two or more development histories together\n>>  SYNOPSIS\n>>  --------\n>>  [verse]\n>> -'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]\n>> -\t[-s <strategy>] [-X <strategy-option>] [-S[<keyid>]]\n>> -\t[--[no-]allow-unrelated-histories]\n>> -\t[--[no-]rerere-autoupdate] [-m <msg>] [<commit>...]\n>> +'git merge' [options] [-m <msg>] [<commit>...]\n>>  'git merge' <msg> HEAD <commit>...\n>>  'git merge' --abort\n>\n> Same comment as 1/6; as we'd hopefully be removing the deprecated\n> form soonish, it would probably make sense to leave only two, i.e.\n>\n> \tgit merge [options] [<commit>...]\n> \tgit merge --abort\n>\n> in synposis.\n\nSame \"yes\" as in 1/6, obviously.\n\n-- Sergey\n"},{"id":"303442","messageId":"871szuqyjo.fsf@javad.com","threadId":"44224","inReplyTo":"xmqq60p6pt4k.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH 5/6] Documentation/git-merge.txt: improve short description in DESCRIPTION","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2016-10-05T21:24:43Z","receivedAt":"2016-10-05T21:24:51Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> sorganov@gmail.com writes:\n>\n>> From: Sergey Organov <sorganov@gmail.com>\n>>\n>> Old description had a few problems:\n>>\n>> - sounded as if commits have changes\n>>\n>> - stated that changes are taken since some \"divergence point\"\n>>   that was not defined.\n>>\n>> New description rather uses \"common ancestor\" and \"merge base\",\n>> definitions of which are easily discoverable in the rest of GIT\n>> documentation.\n>>\n>> Signed-off-by: Sergey Organov <sorganov@gmail.com>\n>> ---\n>>  Documentation/git-merge.txt | 25 +++++++++++++++----------\n>>  1 file changed, 15 insertions(+), 10 deletions(-)\n>>\n>> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\n>> index cc0329d..351b8fc 100644\n>> --- a/Documentation/git-merge.txt\n>> +++ b/Documentation/git-merge.txt\n>> @@ -16,11 +16,16 @@ SYNOPSIS\n>>  \n>>  DESCRIPTION\n>>  -----------\n>> -Incorporates changes from the named commits (since the time their\n>> -histories diverged from the current branch) into the current\n>> -branch.  This command is used by 'git pull' to incorporate changes\n>> -from another repository and can be used by hand to merge changes\n>> -from one branch into another.\n>> +\n>> +Incorporates changes that lead to the named commits into the current\n>> +branch, and joins corresponding histories. The best common ancestor of\n>> +named commits and the current branch, called \"merge base\", is\n>> +calculated, and then net changes taken from the merge base to\n>> +the named commits are applied.\n>> +\n>> +This command is used by 'git pull' to incorporate changes from another\n>> +repository, and can be used by hand to merge changes from one branch\n>> +into another.\n>\n> Content change together with re-flowing the text makes it more\n> costly than necessary to review a change like this.  Please avoid\n> doing so in your future patches.\n\nOK, I see. So, what is the best way to handle this? Immediately follow\ncontent change patch with another patch that only re-flows?\n\n> I like what the updated description says very much.  I however\n> wonder if \"and can be used by hand...\" is still appropriate, or\n> needs a bit of modernizing.  It feels a bit awkward by making it\n> sound as if 'git merge' is primarily an implementation detail of\n> 'git pull' but it can also be used as the first-class command, which\n> used to be the case in the old days back when \"git pull . other\" was\n> also perfectly good way to merge the 'other' branch from your own\n> repository, but I think your update is meant to clarify that we no\n> longer live in that old world ;-)\n\nYes, exactly, but 6/6 removes most of the mentions of git-pull from the\nmanual anyway, so I felt it better belongs there.\n\n>\n>> @@ -31,11 +36,11 @@ Assume the following history exists and the current branch is\n>>      D---E---F---G master\n>>  ------------\n>>  \n>> -Then \"`git merge topic`\" will replay the changes made on the\n>> -`topic` branch since it diverged from `master` (i.e., `E`) until\n>> -its current commit (`C`) on top of `master`, and record the result\n>> -in a new commit along with the names of the two parent commits and\n>> -a log message from the user describing the changes.\n>\n>> -Then \"`git merge topic`\" will replay the changes made on the `topic`\n>> -branch since it diverged from `master` (i.e., `E`) until its current\n>> -commit (`C`) on top of `master`, and record the result in a new commit\n>> -along with the names of the two parent commits and a log message from\n>> -the user describing the changes.\n>\n>> +Then \"`git merge topic`\" will replay the changes made on the `topic`\n>> +branch since it diverged from `master` (i.e., `E`) until its current\n>> +commit (`C`) on top of `master`, and record the result in a new commit\n>> +along with references to the two parent commits and a log message from\n>> +the user describing the changes.\n>\n> Content change together with re-flowing the text makes it more\n> costly than necessary to review a change like this.  Please avoid\n> doing so in your future patches.\n\nYeah, got it.\n\n> I had to re-flow the original you removed to match how you flowed in\n> the updated one and stare at it for a while to spot that the only\n> change was to rephrase \"the names of the parents\" to \"references to\n> the parents\".  I do not know if the updated phrasing is better.  The\n> \"name\" in the original was meant to be a short-hand for \"object name\",\n> and I would support a change to spell it out to clarify; \"reference\"\n> can be a vague word that can mean different things in Git, and when\n> the word is given without context, most Git people would think that\n> the word refers to \"refs\", but that is definitely not what the new\n> commit records, so...\n\nI won't insist on the change, but \"name\" sounded wrong to me, and\n\"reference\" was most general term I was able to come up with in this\ncontext.\n\nFirst, \"name\" somehow suggested that it could be the case that\n\n$ git branch\n* master\n$ git merge topic\n\nwill store strings \"master\" and \"topic\" in the resulting commit.\n\nNext, should one really be aware of \"10.2 Git Internals - Git Objects\"\nto grok this part of the manual if it actually meant to be \"object\nname\"? \n\nLast, if \"reference\" is not good enough and we get to internals anyway,\nwhy not say SHA1 then?\n\n-- Sergey\n"},{"id":"303444","messageId":"87wphmpjvc.fsf@javad.com","threadId":"44224","inReplyTo":"e03a84ad-9aa6-8ada-5828-7b28f76baaaf@gmail.com","subject":"Re: [PATCH 5/6] Documentation/git-merge.txt: improve short description in DESCRIPTION","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2016-10-05T21:27:03Z","receivedAt":"2016-10-05T21:27:09Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Jakub Narębski <jnareb@gmail.com> writes:\n\n> W dniu 05.10.2016 o 16:46, sorganov@gmail.com pisze:\n>> From: Sergey Organov <sorganov@gmail.com>\n>> \n>> Old description had a few problems:\n>> \n>> - sounded as if commits have changes\n>> \n>> - stated that changes are taken since some \"divergence point\"\n>>   that was not defined.\n>> \n>> New description rather uses \"common ancestor\" and \"merge base\",\n>> definitions of which are easily discoverable in the rest of GIT\n>> documentation.\n>\n> This is a step in a good direction, but it has a few issues.\n\nThanks a lot for reviewing! I'll need time to read your reply carefully.\n\n-- Sergey\n"},{"id":"303445","messageId":"87shsapjiz.fsf@javad.com","threadId":"44224","inReplyTo":"xmqqzimioc7s.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH 6/6] Documentation/git-merge.txt: get rid of irrelevant references to git-pull","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2016-10-05T21:34:28Z","receivedAt":"2016-10-05T21:34:35Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> sorganov@gmail.com writes:\n\n[...]\n\n>> @@ -138,14 +133,15 @@ will exit early with the message \"Already up-to-date.\"\n>>  FAST-FORWARD MERGE\n>>  ------------------\n>>  \n>> -Often the current branch head is an ancestor of the named commit.\n>> +Often the current branch head is an ancestor of the named commit.  In\n>> +this case, a new commit is not needed to store the combined history;\n>> +instead, the `HEAD` (along with the index) is updated to point at the\n>> +named commit, without creating an extra merge commit.\n>> +\n>>  This is the most common case especially when invoked from 'git\n>>  pull': you are tracking an upstream repository, you have committed\n>>  no local changes, and now you want to update to a newer upstream\n>> -revision.  In this case, a new commit is not needed to store the\n>> -combined history; instead, the `HEAD` (along with the index) is\n>> -updated to point at the named commit, without creating an extra\n>> -merge commit.\n>> +revision.\n>\n> I am not sure if the post-image of this hunk is better than the\n> original.\n\nThat's what I've tried to explain in the description of the patch:\n\n\"No awareness of git-pull is required to understand git-merge operation,\nso leave reference to git-pull only where it actually makes sense, in\nthe description of fast-forward merges, and only as clarification of\nwhen this merging behaviour is mostly useful.\"\n\nSo I believe this change is inline with the rest of the patch. The\nreference to git-pull (if it remains) should be a side-note, not part of\nexplanation of operation.\n\n-- Sergey\n"},{"id":"303446","messageId":"xmqqa8eio4n9.fsf@gitster.mtv.corp.google.com","threadId":"44224","inReplyTo":"871szuqyjo.fsf@javad.com","subject":"Re: [PATCH 5/6] Documentation/git-merge.txt: improve short description in DESCRIPTION","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-10-05T21:41:14Z","receivedAt":"2016-10-05T21:41:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov <sorganov@gmail.com> writes:\n\n> OK, I see. So, what is the best way to handle this? Immediately follow\n> content change patch with another patch that only re-flows?\n\nOr no reflowing at all.\n\n>> the parents\".  I do not know if the updated phrasing is better.  The\n>> \"name\" in the original was meant to be a short-hand for \"object name\",\n>> and I would support a change to spell it out to clarify; \"reference\"\n>> can be a vague word that can mean different things in Git, and when\n>> the word is given without context, most Git people would think that\n>> the word refers to \"refs\", but that is definitely not what the new\n>> commit records, so...\n>\n> I won't insist on the change, but \"name\" sounded wrong to me, and\n> \"reference\" was most general term I was able to come up with in this\n> context.\n> ...\n> Last, if \"reference\" is not good enough and we get to internals anyway,\n> why not say SHA1 then?\n\nBecause that is still colloquial?  I think s/name/object name/ is\na sensible change, but not s/name/reference/.\n\n"},{"id":"303447","messageId":"xmqq60p6o4js.fsf@gitster.mtv.corp.google.com","threadId":"44224","inReplyTo":"87shsapjiz.fsf@javad.com","subject":"Re: [PATCH 6/6] Documentation/git-merge.txt: get rid of irrelevant references to git-pull","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-10-05T21:43:19Z","receivedAt":"2016-10-05T21:43:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov <sorganov@gmail.com> writes:\n\n> So I believe this change is inline with the rest of the patch. The\n> reference to git-pull (if it remains) should be a side-note, not part of\n> explanation of operation.\n\nNot really.  The thing is, \"This is the most common\" needs to be\nclose to \"Often...\".  \"git merge\" directly invoked by the end user\nis much less likely to encounter a fast forward situation; getting\ninvoked indirectly by \"git pull\" makes it common.\n\n"},{"id":"303479","messageId":"87mvihpsla.fsf@javad.com","threadId":"44224","inReplyTo":"xmqqa8eio4n9.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH 5/6] Documentation/git-merge.txt: improve short description in DESCRIPTION","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2016-10-06T12:30:57Z","receivedAt":"2016-10-06T12:31:25Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Sergey Organov <sorganov@gmail.com> writes:\n>\n>> OK, I see. So, what is the best way to handle this? Immediately follow\n>> content change patch with another patch that only re-flows?\n>\n> Or no reflowing at all.\n>\n>>> the parents\".  I do not know if the updated phrasing is better.  The\n>>> \"name\" in the original was meant to be a short-hand for \"object name\",\n>>> and I would support a change to spell it out to clarify; \"reference\"\n>>> can be a vague word that can mean different things in Git, and when\n>>> the word is given without context, most Git people would think that\n>>> the word refers to \"refs\", but that is definitely not what the new\n>>> commit records, so...\n>>\n>> I won't insist on the change, but \"name\" sounded wrong to me, and\n>> \"reference\" was most general term I was able to come up with in this\n>> context.\n>> ...\n>> Last, if \"reference\" is not good enough and we get to internals anyway,\n>> why not say SHA1 then?\n>\n> Because that is still colloquial? I think s/name/object name/ is a\n> sensible change, but not s/name/reference/.\n\nNo, \"reference\" is more sensible here than any of \"name\", \"object name\",\nor \"SHA-1\", the same way as here:\n\n$ git help glossary\n[...]\nchain\n        A list of objects, where each object in the list contains a\n        reference to its successor (for example, the successor of a\n        commit could be one of its parents).\n[...]\n$\n\nThe resulting merge commit is an origin for 2 chains, so it stores 2\nreferences to its successors. No need to be aware of any [object] names\nto understand all this.\n\n-- Sergey\n"},{"id":"303480","messageId":"87h98pps7a.fsf@javad.com","threadId":"44224","inReplyTo":"xmqq60p6o4js.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH 6/6] Documentation/git-merge.txt: get rid of irrelevant references to git-pull","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2016-10-06T12:39:21Z","receivedAt":"2016-10-06T12:39:29Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Sergey Organov <sorganov@gmail.com> writes:\n>\n>> So I believe this change is inline with the rest of the patch. The\n>> reference to git-pull (if it remains) should be a side-note, not part of\n>> explanation of operation.\n>\n> Not really.  The thing is, \"This is the most common\" needs to be\n> close to \"Often...\".  \"git merge\" directly invoked by the end user\n> is much less likely to encounter a fast forward situation; getting\n> invoked indirectly by \"git pull\" makes it common.\n\nAh, I now see. I tried to keep the text intact as much as possible, and\nonly split it into description and a note. Well, how about this then:\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex b758d55..479400f 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -135,15 +135,17 @@ will exit early with the message \"Already up-to-date.\"\n FAST-FORWARD MERGE\n ------------------\n \n-Often the current branch head is an ancestor of the named commit.\n-This is the most common case especially when invoked from 'git\n-pull': you are tracking an upstream repository, you have committed\n-no local changes, and now you want to update to a newer upstream\n-revision.  In this case, a new commit is not needed to store the\n+When current branch head is an ancestor of the named commit,\n+a new commit is not needed to store the\n combined history; instead, the `HEAD` (along with the index) is\n updated to point at the named commit, without creating an extra\n merge commit.\n \n+This is very common case when 'git merge' is invoked from 'git\n+pull': you are tracking an upstream repository, you have committed\n+no local changes, and now you want to update to a newer upstream\n+revision.  \n+\n This behavior can be suppressed with the `--no-ff` option.\n \n TRUE MERGE\n\n-- Sergey\n\n"},{"id":"303485","messageId":"87a8ehpq98.fsf@javad.com","threadId":"44224","inReplyTo":"e03a84ad-9aa6-8ada-5828-7b28f76baaaf@gmail.com","subject":"Re: [PATCH 5/6] Documentation/git-merge.txt: improve short description in DESCRIPTION","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2016-10-06T13:21:23Z","receivedAt":"2016-10-06T13:21:31Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Jakub Narębski <jnareb@gmail.com> writes:\n\n> W dniu 05.10.2016 o 16:46, sorganov@gmail.com pisze:\n>> From: Sergey Organov <sorganov@gmail.com>\n>> \n>> Old description had a few problems:\n>> \n>> - sounded as if commits have changes\n>> \n>> - stated that changes are taken since some \"divergence point\"\n>>   that was not defined.\n>> \n>> New description rather uses \"common ancestor\" and \"merge base\",\n>> definitions of which are easily discoverable in the rest of GIT\n>> documentation.\n>\n> This is a step in a good direction, but it has a few issues.\n>\n>> \n>> Signed-off-by: Sergey Organov <sorganov@gmail.com>\n>> ---\n>>  Documentation/git-merge.txt | 25 +++++++++++++++----------\n>>  1 file changed, 15 insertions(+), 10 deletions(-)\n>> \n>> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\n>> index cc0329d..351b8fc 100644\n>> --- a/Documentation/git-merge.txt\n>> +++ b/Documentation/git-merge.txt\n>> @@ -16,11 +16,16 @@ SYNOPSIS\n>>  \n>>  DESCRIPTION\n>>  -----------\n>> -Incorporates changes from the named commits (since the time their\n>> -histories diverged from the current branch) into the current\n>> -branch.  This command is used by 'git pull' to incorporate changes\n>> -from another repository and can be used by hand to merge changes\n>> -from one branch into another.\n>> +\n>> +Incorporates changes that lead to the named commits into the current\n>> +branch, and joins corresponding histories. The best common ancestor of\n>> +named commits and the current branch, called \"merge base\", is\n>> +calculated, and then net changes taken from the merge base to\n>> +the named commits are applied.\n>\n> The first sentence is all right; it reads better than the original\n> without the introduced part in parentheses.  The only minor issue\n> is with \"joins corresponding histories\" - it is a good description,\n> but may imply that the branch we are merging vanishes: it doesn't.\n> But all in all, it is a good change.\n\nI've got \"joins corresponding histories\" from original NAME section, so\nit's likely to be good enough.\n\n>\n> Second sentence has some problems.  First, while it is a good idea\n> to use well defined term \"merge base\", I think writing \"since the\n> time their histories diverged\" or \"(which is the point where histories\n> diverged)\" would be a good plain language description; it was removed\n> entirely in the proposal.\n\nI was not sure about it myself, but it sounded as if it could be the\ncase that I might need to resolve the same conflicts again and again, as\nchanges are taken from some \"divergence point\" that is apparently fixed.\n\nOTOH, \"merge base\" not only is well-defined term, but it also doesn't\nsound as some fixed point in history.\n\n>\n> Second, while \"common ancestor\" and \"least common ancestor\" are well\n> defined in mathematics of graphs, \"best common ancestor\" isn't...\n> but this is what git-merge-base(1) documentation uses.\n\nThat's were I took it from indeed, git-merge-base manual page. I wanted\nthings we mention to be discoverable.\n\n> Also, the \"best common ancestor\" doesn't need to be only one.  There\n> might be many such ancestors... though Git would generate then a\n> virtual best common ancestor thanks to recursive merge strategy.\n> And usually there is only one \"best common ancestor\", that is a single\n> merge base.  So this may need clarification, but it is not much of\n> a problem.\n>\n> Third, and most important, is that \"net changes taken from the merge\n> base to the named commits are applied\" is simply not true.  The\n> `git merge` command does not reapply changes - that is what rebase\n> and cherry-pick do.\n\n\"are applied\" meant to be generic enough in this context to cover, say,\n\"-s ours\" as well. Perhaps \"are integrated\" you suggest below, or \"are\nincorporated\" that is already used in the beginning of DESCRIPTION, is\nbetter indeed.\n\nAs for merge vs rebase (or cherry-pick), the only essential difference\nfor me is that merge applies net (cumulative, integrated) changes, while\nrebase applies each change sequentially, one commit to another. Please\ncorrect me if I'm wrong.\n\nBTW, one can imagine \"rebase\" merge strategy: make a new chain of\ncommits on top of destination, then squash all that to get a new single\nmerge commit.\n\n> The merge operation uses 3-way merge strategy (diff3) between\n> merge-base, current branch, and merged commit. That is, it finds\n> differences between differences, and \"applies\" that.\n\nThe problem is that at this point we need to cover other merge\nstrategies as well, so we can't writ the description as if 3-way merge\nis the only strategy.\n\n> See\n> \"A Formal Investigation of Diff3\" paper by Sanjeev Khanna, Keshav\n> Kunal, and Benjamin C. Pierce:\n> http://www.cis.upenn.edu/~bcpierce/papers/diff3-short.pdf\n>\n> I'm not sure how to explain it succintly.  Perhaps\n>\n>   net changes between merge base to the current (merged into)\n>   branch and named commits are integrated\n>\n> There is description of trivial 3-way merge somewhere in Git docs,\n> though in very unobvious place; we can link it.\n\nAs it's \"TRUE MERGE\" section that mentions 3-way merge for the first\ntime, it'd be the natural place for the link, I think.\n\n>> +\n>> +This command is used by 'git pull' to incorporate changes from another\n>> +repository, and can be used by hand to merge changes from one branch\n>> +into another.\n>\n> Rather \"can be used by 'git pull'\", or \"is used by 'git pull' (unless\n> configured otherwise)\"...\n>\n> Separating this information makes a very good sense.  Thanks.\n\nYeah, but I've rather deleted it entirely in 6/6.\n\n-- Sergey.\n"},{"id":"303506","messageId":"xmqqshs9l69h.fsf@gitster.mtv.corp.google.com","threadId":"44224","inReplyTo":"87mvihpsla.fsf@javad.com","subject":"Re: [PATCH 5/6] Documentation/git-merge.txt: improve short description in DESCRIPTION","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-10-06T17:46:50Z","receivedAt":"2016-10-06T17:47:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov <sorganov@gmail.com> writes:\n\n>>> Last, if \"reference\" is not good enough and we get to internals anyway,\n>>> why not say SHA1 then?\n>>\n>> Because that is still colloquial? I think s/name/object name/ is a\n>> sensible change, but not s/name/reference/.\n>\n> No, \"reference\" is more sensible here than any of \"name\", \"object name\",\n> or \"SHA-1\", the same way as here:\n>\n> $ git help glossary\n> [...]\n> chain\n>         A list of objects, where each object in the list contains a\n>         reference to its successor (for example, the successor of a\n>         commit could be one of its parents).\n> [...]\n\nThe entry for \"chain\" and the description under discussion have\nstress on different aspect, though.  The description of \"chain\" is\nmore general: an object refers to another object by referring to it,\nby unspecified means.  The reason why it is left unspecified is\nbecause the way a tree object refers to blobs and trees is different\nfrom the way a commit object refers to its parents (the former has\nobject names of blobs and trees in the tree entries; the latter uses\n\"parent\" entries in the object header part to record object names of\nparent commits).  It wants to stress more on the fact that there is\nsome mechanism to associate one object to others, than how that\nassociation/linkage is expressed.\n\nThe way the resulting commit is described in the original text of\n\"git merge\" description stresses more on \"how\" by being a lot more\nspecific to commit objects.  It does not just say \"refers to parents\n(by unspecified means)\"; instead it tries to say what exactly are\nrecorded, i.e. the parents are referred to by recording the object\nnames of them in a new commit object.  It stresses more on \"how\"\n(because it can afford to be more specific, unlike the description\nof more general concept of a \"chain\").\n\nIt may be debatable if we want to give the description of what is\nexactly recorded at that point of the document, but I personally\nthink that the users deserve a chance to learn how a merge is\nrecorded in \"git merge\" documentation.\n\n\n"},{"id":"303507","messageId":"xmqqmvihl5df.fsf@gitster.mtv.corp.google.com","threadId":"44224","inReplyTo":"87h98pps7a.fsf@javad.com","subject":"Re: [PATCH 6/6] Documentation/git-merge.txt: get rid of irrelevant references to git-pull","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-10-06T18:06:04Z","receivedAt":"2016-10-06T18:06:44Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov <sorganov@gmail.com> writes:\n\n> Ah, I now see. I tried to keep the text intact as much as possible, and\n> only split it into description and a note. Well, how about this then:\n\nMuch better than your earlier patch, but I am not sure if the\nupdated one is that much better compared to the original.\n\nThe pre- and post- state of this \"how about this\" patch essentially\nsay the same thing, and I suspect that the primary reason why you\nthink the post- state is easier to read is because you wrote it,\nwhile the reason why I do not see much difference is because I\ndidn't write the updated one ;-).\n\nI do find \"In this case, ... store the combined history\" in the\noriginal a bit awkward to read, but most of that awkardness is\ninherited by the updated text.  It may benefit from hinting why a\nnew commit is not needed a bit stronger.  Here is my attempt:\n\n    When the commit we are merging is a descendant of the current\n    HEAD, the history leading to the named commit can be, and by\n    default is, taken as the combined history of the two.  Our\n    history is \"fast forwarded\" to their history by updating `HEAD`\n    along with the index to point at the named commit.\n\n    This often happens when you are following along somebody else's\n    work via \"git pull\" without doing your own development.\n\nI think the awkwardness I felt in the original and your version is\ngone from the above attempt, but I doubt that it is better over\neither of them in any other way.\n\n> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\n> index b758d55..479400f 100644\n> --- a/Documentation/git-merge.txt\n> +++ b/Documentation/git-merge.txt\n> @@ -135,15 +135,17 @@ will exit early with the message \"Already up-to-date.\"\n>  FAST-FORWARD MERGE\n>  ------------------\n>  \n> -Often the current branch head is an ancestor of the named commit.\n> -This is the most common case especially when invoked from 'git\n> -pull': you are tracking an upstream repository, you have committed\n> -no local changes, and now you want to update to a newer upstream\n> -revision.  In this case, a new commit is not needed to store the\n> +When current branch head is an ancestor of the named commit,\n> +a new commit is not needed to store the\n>  combined history; instead, the `HEAD` (along with the index) is\n>  updated to point at the named commit, without creating an extra\n>  merge commit.\n>  \n> +This is very common case when 'git merge' is invoked from 'git\n> +pull': you are tracking an upstream repository, you have committed\n> +no local changes, and now you want to update to a newer upstream\n> +revision.  \n> +\n>  This behavior can be suppressed with the `--no-ff` option.\n>  \n>  TRUE MERGE\n>\n> -- Sergey\n"},{"id":"303554","messageId":"87mvigmlgi.fsf@javad.com","threadId":"44224","inReplyTo":"xmqqmvihl5df.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH 6/6] Documentation/git-merge.txt: get rid of irrelevant references to git-pull","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2016-10-07T11:45:33Z","receivedAt":"2016-10-07T11:45:41Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Sergey Organov <sorganov@gmail.com> writes:\n>\n>> Ah, I now see. I tried to keep the text intact as much as possible, and\n>> only split it into description and a note. Well, how about this then:\n>\n> Much better than your earlier patch, but I am not sure if the\n> updated one is that much better compared to the original.\n\nIt's not intended to be much better. It is aimed at single simple\ntarget: get rid of git-pull from descriptions of operations of\ngit-merge.\n\nI'd just remove those git-pull reference, the only one that is left\nafter the patch, but it looks like git-merge needs an excuse to have\nfast-forward on by default, and that excuse is the common git-pull case.\n\n[I'd prefer 'git-merge --ff' were called from 'git-pull' and --no-ff be\nthe default for git-merge, but that's not the case, so I left the\nreference to git-pull intact.]\n\n>\n> The pre- and post- state of this \"how about this\" patch essentially\n> say the same thing, and I suspect that the primary reason why you\n> think the post- state is easier to read is because you wrote it,\n> while the reason why I do not see much difference is because I\n> didn't write the updated one ;-).\n>\n> I do find \"In this case, ... store the combined history\" in the\n> original a bit awkward to read, but most of that awkardness is\n> inherited by the updated text.  It may benefit from hinting why a\n> new commit is not needed a bit stronger.  Here is my attempt:\n>\n>     When the commit we are merging is a descendant of the current\n>     HEAD, the history leading to the named commit can be, and by\n>     default is, taken as the combined history of the two.  Our\n>     history is \"fast forwarded\" to their history by updating `HEAD`\n>     along with the index to point at the named commit.\n>\n>     This often happens when you are following along somebody else's\n>     work via \"git pull\" without doing your own development.\n>\n> I think the awkwardness I felt in the original and your version is\n> gone from the above attempt, but I doubt that it is better over\n> either of them in any other way.\n\nThis is entirely different matter, and should be a subject of another\npatch, if any. My patch meant to only address git-pull references, with\nas few changes as possible.\n\n-- Sergey\n"},{"id":"303560","messageId":"878tu0mhdj.fsf@javad.com","threadId":"44224","inReplyTo":"xmqqshs9l69h.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH 5/6] Documentation/git-merge.txt: improve short description in DESCRIPTION","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2016-10-07T13:13:44Z","receivedAt":"2016-10-07T13:13:57Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Sergey Organov <sorganov@gmail.com> writes:\n>\n>>>> Last, if \"reference\" is not good enough and we get to internals anyway,\n>>>> why not say SHA1 then?\n>>>\n>>> Because that is still colloquial? I think s/name/object name/ is a\n>>> sensible change, but not s/name/reference/.\n>>\n>> No, \"reference\" is more sensible here than any of \"name\", \"object name\",\n>> or \"SHA-1\", the same way as here:\n>>\n>> $ git help glossary\n>> [...]\n>> chain\n>>         A list of objects, where each object in the list contains a\n>>         reference to its successor (for example, the successor of a\n>>         commit could be one of its parents).\n>> [...]\n>\n> The entry for \"chain\" and the description under discussion have\n> stress on different aspect, though.  The description of \"chain\" is\n> more general: an object refers to another object by referring to it,\n> by unspecified means.  The reason why it is left unspecified is\n> because the way a tree object refers to blobs and trees is different\n> from the way a commit object refers to its parents (the former has\n> object names of blobs and trees in the tree entries; the latter uses\n> \"parent\" entries in the object header part to record object names of\n> parent commits).  It wants to stress more on the fact that there is\n> some mechanism to associate one object to others, than how that\n> association/linkage is expressed.\n>\n> The way the resulting commit is described in the original text of\n> \"git merge\" description stresses more on \"how\" by being a lot more\n> specific to commit objects.  It does not just say \"refers to parents\n> (by unspecified means)\"; instead it tries to say what exactly are\n> recorded, i.e. the parents are referred to by recording the object\n> names of them in a new commit object.  It stresses more on \"how\"\n> (because it can afford to be more specific, unlike the description\n> of more general concept of a \"chain\").\n\nThat's were our disagreement actually is, and that's what I've tried to\nfix with s/name/reference/, and that's why I'm against s/name/object\nname/.\n\nRather than being more (and more) specific at every opportunity, one\nneeds a good reason to get more specific. In this particular case,\ngeneral DAG terminology seems to be enough to describe git-merge\nsemantics, thus using GIT specifics is unfounded.\n\n> It may be debatable if we want to give the description of what is\n> exactly recorded at that point of the document,\n\nExactly. My point in this particular discussion is that details of\nrecording of references to parents don't belong here, even though to\ntell the truth I think they don't belong to git _user_ documentation at\nall.\n\n> but I personally\n> think that the users deserve a chance to learn how a merge is\n> recorded in \"git merge\" documentation.\n\nI doubt a user will gain anything from this sacred knowledge suddenly\nbeing thrown on him when what she is looking for is understanding of\nbasic merge semantics in GIT.\n\nThat said, if you still disagree, please feel free to just drop the\npatch.\n\n-- Sergey\n"}]}