Re: Re* [PATCH 2/4] refs: trim newline from reflog message

From: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
To: Junio C Hamano <gitster@pobox.com>
Cc: Han-Wen Nienhuys <hanwen@google.com>,
	Han-Wen Nienhuys via GitGitGadget <gitgitgadget@gmail.com>,
	git@vger.kernel.org, Han-Wen Nienhuys <hanwenn@gmail.com>
Subject: Re: Re* [PATCH 2/4] refs: trim newline from reflog message
Date: Sun, 28 Nov 2021 18:50:15 +0100	[thread overview]
Message-ID: <211128.86r1b0gnv6.gmgdl@evledraar.gmail.com> (raw)
In-Reply-To: <xmqqczmn71ru.fsf_-_@gitster.g>

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.