[GSoC][PATCH] commit: warn the usage of reverse_commit_list() helper

[Kousik Sanagavarapu <five231003@gmail.com>]

The helper function reverse_commit_list() has destructive behavior when
used to reverse a list in-place. Warn about this behavior.

Signed-off-by: Kousik Sanagavarapu <five231003@gmail.com>
---

This patch has been sent based on the confusion that can be caused while
using the reverse_commit_list() helper function. One example of this is
a recent patch that I submitted[1] where the use of this function broke
try_merge_strategy() in merge.

It is also based on the discussions[2] there that I send this patch.

[1]: https://lore.kernel.org/git/20230202165137.118741-1-five231003@gmail.com/
[2]: https://lore.kernel.org/git/xmqqmt5uo9ea.fsf@gitster.g/

 commit.h | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/commit.h b/commit.h
index fa39202fa6..9dba07748f 100644
--- a/commit.h
+++ b/commit.h
@@ -198,7 +198,12 @@ void commit_list_sort_by_date(struct commit_list **list);
 /* Shallow copy of the input list */
 struct commit_list *copy_commit_list(struct commit_list *list);
 
-/* Modify list in-place to reverse it, returning new head; list will be tail */
+/*
+ * Modify list in-place to reverse it, returning new head; list will be tail.
+ *
+ * NOTE! The reversed list is constructed using the elements of the original
+ * list, hence losing the original list.
+ */
 struct commit_list *reverse_commit_list(struct commit_list *list);
 
 void free_commit_list(struct commit_list *list);
-- 
2.25.1