| Message ID | xmqqczmn71ru.fsf_-_@gitster.g (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Re* [PATCH 2/4] refs: trim newline from reflog message | expand |
On Fri, Nov 26 2021, Junio C Hamano wrote: > Junio C Hamano <gitster@pobox.com> writes: > >> I think what deserves such a comment more is the prototype for >> each_reflog_ent_fn describing what the parameters to that callback >> function, to help the callers of the iterator what to expect. That >> is the end-user facing part. > > Perhaps something along this line. > > --- >8 ------ >8 ------ >8 ------ >8 ------ >8 ------ >8 --- > Subject: [PATCH] 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. > > Signed-off-by: Junio C Hamano <gitster@pobox.com> > --- > refs.h | 22 +++++++++++++++++++++- > 1 file changed, 21 insertions(+), 1 deletion(-) > > diff --git c/refs.h w/refs.h > index 48970dfc7e..4fa97d77cf 100644 > --- c/refs.h > +++ w/refs.h > @@ -462,7 +462,27 @@ 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 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 Line and Attu islands beg to differ :) 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.
Ævar Arnfjörð Bjarmason <avarab@gmail.com> 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. Thanks.
diff --git c/refs.h w/refs.h index 48970dfc7e..4fa97d77cf 100644 --- c/refs.h +++ w/refs.h @@ -462,7 +462,27 @@ 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 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 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,