refs: document callback for reflog-ent iterators
refs_for_each_reflog_ent() and refs_for_each_reflog_ent_reverse() functions take a callback function that gets called with the details of each reflog entry. Its parameters were not documented beyond their names. Elaborate a bit on each of them. Helped-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Nov 28, 2021 at 11:25 UTC
e6e94f34b28e52e31436c79d94511ed78050042f
1 file changed
+23
-1
refs.h
+23
-1
@@ -462,7 +462,29 @@ int delete_reflog(const char *refname);
462
463
/*
464
* Callback to process a reflog entry found by the iteration functions (see
465
- * below)
465
+ * below).
466
+ *
467
+ * The committer parameter is a single string, in the form
468
+ * "$GIT_COMMITTER_NAME <$GIT_COMMITTER_EMAIL>" (without double quotes).
469
+ *
470
+ * The timestamp parameter gives the time when entry was created as the number
471
+ * of seconds since the UNIX epoch.
472
+ *
473
+ * The tz parameter gives the timezone offset for the user who created
474
+ * the reflog entry, and its value gives a positive or negative offset
475
+ * from UTC. Its absolute value is formed by multiplying the hour
476
+ * part by 100 and adding the minute part. For example, 1 hour ahead
477
+ * of UTC, CET == "+0100", is represented as positive one hundred (not
478
+ * postiive sixty).
479
+ *
480
+ * The msg parameter is a single complete line; a reflog message given
481
+ * to refs_delete_ref, refs_update_ref, etc. is returned to the
482
+ * callback normalized---each run of whitespaces are squashed into a
483
+ * single whitespace, trailing whitespace, if exists, is trimmed, and
484
+ * then a single LF is added at the end.
485
+ *
486
+ * The cb_data is a caller-supplied pointer given to the iterator
487
+ * functions.
488
*/
489
typedef int each_reflog_ent_fn(
490
struct object_id *old_oid, struct object_id *new_oid,