Junio C Hamano <gitster@xxxxxxxxx> writes:
> Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> writes:
>
>> Nitpicking aside, perhaps these two pargaraphs would be better as simply
>> replaced by:
>>
>> Consult "Git internal format" in git-commit-tree(1) for
>> details about the "<unix timestamp> <time zone offset>" format, and
>> see show_one_reflog_ent() for the parsing function.
>
> Much nicer; this is developer facing and reducing risk of
> inconsistency by incorrectly duplicating is much more important than
> having the info available in a single place.
Having actually read the description, I do not think
"Documentation/date-formats.txt::Git internal format" is a good fit.
We are describing the format of a single string there (e.g. <unix
timestamp> and <time zone offset> form a single string with one SP
in between), but the parameters are integral types.
Specifically because the "Git internal format" is textual, an
example "+0100" given there makes it sufficiently clear that the
offset is a "a sign followed by 4 digits" string, but those who need
to use the value in "int tz" must know that is represented as a
positive one hundred, not sixty, which does not have to be captured
there for the intended audience of date-formats.txt pagelet.
Here is what I came up with
---- >8 -------- >8 -------- >8 -------- >8 -------- >8 ----
Subject: [PATCH v2] 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@xxxxxxxxx>
Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx>
---
* rewrite timestamp and tz, adjusting the internal format's
description from Documentation/date-formats.txt pagelet, as
pointed out by Ævar.
refs.h | 24 +++++++++++++++++++++++-
1 file changed, 23 insertions(+), 1 deletion(-)
The indented patch shows the part that was changed from the
previous one.
diff --git i/refs.h w/refs.h
index 4fa97d77cf..f6fed5c7d8 100644
--- i/refs.h
+++ w/refs.h
@@ -467,13 +467,15 @@ int delete_reflog(const char *refname);
* The committer parameter is a single string, in the form
* "$GIT_COMMITTER_NAME <$GIT_COMMITTER_EMAIL>" (without double quotes).
*
- * The timestamp parameter gives the seconds since epoch when the reflog
- * entry was created.
- *
- * The tz parameter is an up to 4 digits integer, whose absolute value
- * gives the hour and minute offset from GMT (the lower 2 digits are
- * minutes, the higher 2 digits are hours). A negative tz means west of,
- * and a positive tz means east of GMT.
+ * The timestamp parameter gives the time when entry was created as the number
+ * of seconds since the UNIX epoch.
+ *
+ * The tz parameter gives the timezone offset for the user who created
+ * the reflog entry, and its value gives a positive or negative offset
+ * from UTC. Its absolute value is formed by multiplying the hour
+ * part by 100 and adding the minute part. For example, 1 hour ahead
+ * of UTC, CET == "+0100", is represented as positive one hundred (not
+ * postiive sixty).
*
* The msg parameter is a single complete line; a reflog message given
* to refs_delete_ref, refs_update_ref, etc. is returned to the
diff --git c/refs.h w/refs.h
index 48970dfc7e..f6fed5c7d8 100644
--- c/refs.h
+++ w/refs.h
@@ -462,7 +462,29 @@ int delete_reflog(const char *refname);
/*
* Callback to process a reflog entry found by the iteration functions (see
- * below)
+ * below).
+ *
+ * The committer parameter is a single string, in the form
+ * "$GIT_COMMITTER_NAME <$GIT_COMMITTER_EMAIL>" (without double quotes).
+ *
+ * The timestamp parameter gives the time when entry was created as the number
+ * of seconds since the UNIX epoch.
+ *
+ * The tz parameter gives the timezone offset for the user who created
+ * the reflog entry, and its value gives a positive or negative offset
+ * from UTC. Its absolute value is formed by multiplying the hour
+ * part by 100 and adding the minute part. For example, 1 hour ahead
+ * of UTC, CET == "+0100", is represented as positive one hundred (not
+ * postiive sixty).
+ *
+ * The msg parameter is a single complete line; a reflog message given
+ * to refs_delete_ref, refs_update_ref, etc. is returned to the
+ * callback normalized---each run of whitespaces are squashed into a
+ * single whitespace, trailing whitespace, if exists, is trimmed, and
+ * then a single LF is added at the end.
+ *
+ * The cb_data is a caller-supplied pointer given to the iterator
+ * functions.
*/
typedef int each_reflog_ent_fn(
struct object_id *old_oid, struct object_id *new_oid,
