merge-recursive: fix unclear and outright wrong comments
Commits 7c0a6c8e47 ("merge-recursive: move some definitions around to clean up the header", 2019-08-17), and b4db8a2b76 ("merge-recursive: remove useless parameter in merge_trees()", 2019-08-17) added some useful documentation to the functions, but had a few places where the new comments were unclear or even misleading. Fix those comments. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Elijah Newren committed
Aug 2, 2020 at 03:14 UTC
56e743426b183d8aea8f4caa363e7f3c7da27278
2 files changed
+9
-9
merge-recursive.c
+3
-2
@@ -3529,8 +3529,9 @@ static struct commit_list *reverse_commit_list(struct commit_list *list)
3529
}
3530
3531
/*
3532
- * Merge the commits h1 and h2, return the resulting virtual
3533
- * commit object and a flag indicating the cleanness of the merge.
3532
+ * Merge the commits h1 and h2, returning a flag (int) indicating the
3533
+ * cleanness of the merge. Also, if opt->priv->call_depth, create a
3534
+ * virtual commit and write its location to *result.
3535
*/
3536
static int merge_recursive_internal(struct merge_options *opt,
3537
struct commit *h1,
merge-recursive.h
+6
-7
@@ -69,9 +69,8 @@ int parse_merge_opt(struct merge_options *opt, const char *s);
69
*
70
* Outputs:
71
* - See RETURN VALUES above
72
- * - No commit is created
72
* - opt->repo->index has the new index
74
- * - $GIT_INDEX_FILE is not updated
73
+ * - new index NOT written to disk
74
* - The working tree is updated with results of the merge
75
*/
76
int merge_trees(struct merge_options *opt,
@@ -81,7 +80,7 @@ int merge_trees(struct merge_options *opt,
80
81
/*
82
* merge_recursive is like merge_trees() but with recursive ancestor
84
- * consolidation and, if the commit is clean, creation of a commit.
83
+ * consolidation.
84
*
85
* NOTE: empirically, about a decade ago it was determined that with more
86
* than two merge bases, optimal behavior was found when the
@@ -91,9 +90,9 @@ int merge_trees(struct merge_options *opt,
90
*
91
* Outputs:
92
* - See RETURN VALUES above
94
- * - If merge is clean, a commit is created and its address written to *result
93
+ * - *result is treated as scratch space for temporary recursive merges
94
* - opt->repo->index has the new index
96
- * - $GIT_INDEX_FILE is not updated
95
+ * - new index NOT written to disk
96
* - The working tree is updated with results of the merge
97
*/
98
int merge_recursive(struct merge_options *opt,
@@ -109,9 +108,9 @@ int merge_recursive(struct merge_options *opt,
108
*
109
* Outputs:
110
* - See RETURN VALUES above
112
- * - If merge is clean, a commit is created and its address written to *result
111
+ * - *result is treated as scratch space for temporary recursive merges
112
* - opt->repo->index has the new index
114
- * - $GIT_INDEX_FILE is updated
113
+ * - new index also written to $GIT_INDEX_FILE on disk
114
* - The working tree is updated with results of the merge
115
*/
116
int merge_recursive_generic(struct merge_options *opt,