Git Mailing List Archive on lore.kernel.org
 help / color / Atom feed
* [PATCH] merge-recursive: fix unclear and outright wrong comments
@ 2020-08-02  3:14 Elijah Newren via GitGitGadget
  0 siblings, 0 replies; only message in thread
From: Elijah Newren via GitGitGadget @ 2020-08-02  3:14 UTC (permalink / raw)
  To: git; +Cc: Elijah Newren, Elijah Newren

From: Elijah Newren <newren@gmail.com>

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>
---
    fix unclear and misleading comments in merge-recursive

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-826%2Fnewren%2Ffix-merge-recursive-comments-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-826/newren/fix-merge-recursive-comments-v1
Pull-Request: https://github.com/git/git/pull/826

 merge-recursive.c |  5 +++--
 merge-recursive.h | 13 ++++++-------
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/merge-recursive.c b/merge-recursive.c
index 36948eafb7..01c633d807 100644
--- a/merge-recursive.c
+++ b/merge-recursive.c
@@ -3529,8 +3529,9 @@ static struct commit_list *reverse_commit_list(struct commit_list *list)
 }
 
 /*
- * Merge the commits h1 and h2, return the resulting virtual
- * commit object and a flag indicating the cleanness of the merge.
+ * Merge the commits h1 and h2, returning a flag (int) indicating the
+ * cleanness of the merge.  Also, if opt->priv->call_depth, create a
+ * virtual commit and write its location to *result.
  */
 static int merge_recursive_internal(struct merge_options *opt,
 				    struct commit *h1,
diff --git a/merge-recursive.h b/merge-recursive.h
index 978847e672..0795a1d3ec 100644
--- a/merge-recursive.h
+++ b/merge-recursive.h
@@ -69,9 +69,8 @@ int parse_merge_opt(struct merge_options *opt, const char *s);
  *
  * Outputs:
  *   - See RETURN VALUES above
- *   - No commit is created
  *   - opt->repo->index has the new index
- *   - $GIT_INDEX_FILE is not updated
+ *   - new index NOT written to disk
  *   - The working tree is updated with results of the merge
  */
 int merge_trees(struct merge_options *opt,
@@ -81,7 +80,7 @@ int merge_trees(struct merge_options *opt,
 
 /*
  * merge_recursive is like merge_trees() but with recursive ancestor
- * consolidation and, if the commit is clean, creation of a commit.
+ * consolidation.
  *
  * NOTE: empirically, about a decade ago it was determined that with more
  *       than two merge bases, optimal behavior was found when the
@@ -91,9 +90,9 @@ int merge_trees(struct merge_options *opt,
  *
  * Outputs:
  *   - See RETURN VALUES above
- *   - If merge is clean, a commit is created and its address written to *result
+ *   - *result is treated as scratch space for temporary recursive merges
  *   - opt->repo->index has the new index
- *   - $GIT_INDEX_FILE is not updated
+ *   - new index NOT written to disk
  *   - The working tree is updated with results of the merge
  */
 int merge_recursive(struct merge_options *opt,
@@ -109,9 +108,9 @@ int merge_recursive(struct merge_options *opt,
  *
  * Outputs:
  *   - See RETURN VALUES above
- *   - If merge is clean, a commit is created and its address written to *result
+ *   - *result is treated as scratch space for temporary recursive merges
  *   - opt->repo->index has the new index
- *   - $GIT_INDEX_FILE is updated
+ *   - new index also written to $GIT_INDEX_FILE on disk
  *   - The working tree is updated with results of the merge
  */
 int merge_recursive_generic(struct merge_options *opt,

base-commit: 47ae905ffb98cc4d4fd90083da6bc8dab55d9ecc
-- 
gitgitgadget

^ permalink raw reply	[flat|nested] only message in thread

only message in thread, back to index

Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-08-02  3:14 [PATCH] merge-recursive: fix unclear and outright wrong comments Elijah Newren via GitGitGadget

Git Mailing List Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/git/0 git/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 git git/ https://lore.kernel.org/git \
		git@vger.kernel.org
	public-inbox-index git

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.git


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git