{"thread":{"id":"53962","subject":"[PATCH] merge-recursive: fix unclear and outright wrong comments","startedAt":"2020-08-02T03:14:32Z","lastAt":"2020-08-02T03:14:32Z","messageCount":1,"participants":["Elijah Newren via GitGitGadget"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"402637","messageId":"pull.826.git.git.1596338068072.gitgitgadget@gmail.com","threadId":"53962","inReplyTo":null,"subject":"[PATCH] merge-recursive: fix unclear and outright wrong comments","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2020-08-02T03:14:27Z","receivedAt":"2020-08-02T03:14:32Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren <newren@gmail.com>\n\nCommits 7c0a6c8e47 (\"merge-recursive: move some definitions around to\nclean up the header\", 2019-08-17), and b4db8a2b76 (\"merge-recursive:\nremove useless parameter in merge_trees()\", 2019-08-17) added some\nuseful documentation to the functions, but had a few places where the\nnew comments were unclear or even misleading.  Fix those comments.\n\nSigned-off-by: Elijah Newren <newren@gmail.com>\n---\n    fix unclear and misleading comments in merge-recursive\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-826%2Fnewren%2Ffix-merge-recursive-comments-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-826/newren/fix-merge-recursive-comments-v1\nPull-Request: https://github.com/git/git/pull/826\n\n merge-recursive.c |  5 +++--\n merge-recursive.h | 13 ++++++-------\n 2 files changed, 9 insertions(+), 9 deletions(-)\n\ndiff --git a/merge-recursive.c b/merge-recursive.c\nindex 36948eafb7..01c633d807 100644\n--- a/merge-recursive.c\n+++ b/merge-recursive.c\n@@ -3529,8 +3529,9 @@ static struct commit_list *reverse_commit_list(struct commit_list *list)\n }\n \n /*\n- * Merge the commits h1 and h2, return the resulting virtual\n- * commit object and a flag indicating the cleanness of the merge.\n+ * Merge the commits h1 and h2, returning a flag (int) indicating the\n+ * cleanness of the merge.  Also, if opt->priv->call_depth, create a\n+ * virtual commit and write its location to *result.\n  */\n static int merge_recursive_internal(struct merge_options *opt,\n \t\t\t\t    struct commit *h1,\ndiff --git a/merge-recursive.h b/merge-recursive.h\nindex 978847e672..0795a1d3ec 100644\n--- a/merge-recursive.h\n+++ b/merge-recursive.h\n@@ -69,9 +69,8 @@ int parse_merge_opt(struct merge_options *opt, const char *s);\n  *\n  * Outputs:\n  *   - See RETURN VALUES above\n- *   - No commit is created\n  *   - opt->repo->index has the new index\n- *   - $GIT_INDEX_FILE is not updated\n+ *   - new index NOT written to disk\n  *   - The working tree is updated with results of the merge\n  */\n int merge_trees(struct merge_options *opt,\n@@ -81,7 +80,7 @@ int merge_trees(struct merge_options *opt,\n \n /*\n  * merge_recursive is like merge_trees() but with recursive ancestor\n- * consolidation and, if the commit is clean, creation of a commit.\n+ * consolidation.\n  *\n  * NOTE: empirically, about a decade ago it was determined that with more\n  *       than two merge bases, optimal behavior was found when the\n@@ -91,9 +90,9 @@ int merge_trees(struct merge_options *opt,\n  *\n  * Outputs:\n  *   - See RETURN VALUES above\n- *   - If merge is clean, a commit is created and its address written to *result\n+ *   - *result is treated as scratch space for temporary recursive merges\n  *   - opt->repo->index has the new index\n- *   - $GIT_INDEX_FILE is not updated\n+ *   - new index NOT written to disk\n  *   - The working tree is updated with results of the merge\n  */\n int merge_recursive(struct merge_options *opt,\n@@ -109,9 +108,9 @@ int merge_recursive(struct merge_options *opt,\n  *\n  * Outputs:\n  *   - See RETURN VALUES above\n- *   - If merge is clean, a commit is created and its address written to *result\n+ *   - *result is treated as scratch space for temporary recursive merges\n  *   - opt->repo->index has the new index\n- *   - $GIT_INDEX_FILE is updated\n+ *   - new index also written to $GIT_INDEX_FILE on disk\n  *   - The working tree is updated with results of the merge\n  */\n int merge_recursive_generic(struct merge_options *opt,\n\nbase-commit: 47ae905ffb98cc4d4fd90083da6bc8dab55d9ecc\n-- \ngitgitgadget\n"}]}