On Sun, Nov 28 2021, Junio C Hamano wrote: > 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 Thanks, this version of these docs looks good to me!
