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: Mon, 29 Nov 2021 09:39:58 +0100 [thread overview]
Message-ID: <211129.86h7bvgvqt.gmgdl@evledraar.gmail.com> (raw)
In-Reply-To: <xmqqk0gs5bgw.fsf@gitster.g>
On Sun, Nov 28 2021, Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>
>> Æ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.
>
> 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@gmail.com>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>
> * 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!
next prev parent reply other threads:[~2021-11-29 9:42 UTC|newest]
Thread overview: 60+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-11-22 14:20 [PATCH 0/4] Inspect reflog data programmatically in more tests Han-Wen Nienhuys via GitGitGadget
2021-11-22 14:20 ` [PATCH 1/4] show-branch: show reflog message Han-Wen Nienhuys via GitGitGadget
2021-11-22 22:22 ` Junio C Hamano
2021-11-23 7:40 ` Bagas Sanjaya
2021-11-23 8:03 ` Elijah Newren
2021-11-22 14:20 ` [PATCH 2/4] refs: trim newline from " Han-Wen Nienhuys via GitGitGadget
2021-11-22 22:27 ` Junio C Hamano
2021-11-23 16:35 ` Han-Wen Nienhuys
2021-11-23 17:09 ` Junio C Hamano
2021-11-23 17:28 ` Han-Wen Nienhuys
2021-11-23 20:34 ` Junio C Hamano
2021-11-24 11:17 ` Han-Wen Nienhuys
2021-11-24 18:53 ` Junio C Hamano
2021-11-24 19:06 ` Han-Wen Nienhuys
2021-11-24 20:55 ` Junio C Hamano
2021-11-25 16:00 ` Han-Wen Nienhuys
2021-11-29 2:30 ` Junio C Hamano
2021-11-24 19:26 ` Junio C Hamano
2021-11-24 19:39 ` Han-Wen Nienhuys
2021-11-26 8:35 ` Re* " Junio C Hamano
2021-11-28 17:50 ` Ævar Arnfjörð Bjarmason
2021-11-28 18:59 ` Junio C Hamano
2021-11-28 19:25 ` Junio C Hamano
2021-11-29 8:39 ` Ævar Arnfjörð Bjarmason [this message]
2021-11-23 10:24 ` Ævar Arnfjörð Bjarmason
2021-11-23 16:44 ` Han-Wen Nienhuys
2021-11-22 14:20 ` [PATCH 3/4] test-ref-store: tweaks to for-each-reflog-ent format Han-Wen Nienhuys via GitGitGadget
2021-11-22 22:31 ` Junio C Hamano
2021-11-23 17:06 ` Han-Wen Nienhuys
2021-11-23 18:31 ` Junio C Hamano
2021-11-22 14:20 ` [PATCH 4/4] t1400: use test-helper ref-store to inspect reflog contents Han-Wen Nienhuys via GitGitGadget
2021-11-22 15:20 ` Ævar Arnfjörð Bjarmason
2021-11-22 17:07 ` Han-Wen Nienhuys
2021-11-22 22:22 ` Junio C Hamano
2021-11-25 15:57 ` [PATCH v2 0/5] Inspect reflog data programmatically in more tests Han-Wen Nienhuys via GitGitGadget
2021-11-25 15:57 ` [PATCH v2 1/5] show-branch: show reflog message Han-Wen Nienhuys via GitGitGadget
2021-11-25 15:57 ` [PATCH v2 2/5] test-ref-store: don't add newline to " Han-Wen Nienhuys via GitGitGadget
2021-11-26 7:56 ` Junio C Hamano
2021-11-25 15:57 ` [PATCH v2 3/5] t1405: check for_each_reflog_ent_reverse() more thoroughly Han-Wen Nienhuys via GitGitGadget
2021-11-25 15:57 ` [PATCH v2 4/5] test-ref-store: tweaks to for-each-reflog-ent format Han-Wen Nienhuys via GitGitGadget
2021-11-26 8:02 ` Junio C Hamano
2021-11-25 15:57 ` [PATCH v2 5/5] refs/debug: trim trailing LF from reflog message Han-Wen Nienhuys via GitGitGadget
2021-11-26 8:16 ` Junio C Hamano
2021-11-29 18:29 ` Han-Wen Nienhuys
2021-11-29 19:19 ` Junio C Hamano
2021-11-29 19:35 ` Junio C Hamano
2021-12-02 16:24 ` Han-Wen Nienhuys
2021-12-02 18:36 ` Junio C Hamano
2021-11-29 20:59 ` Ævar Arnfjörð Bjarmason
2021-11-29 9:50 ` [PATCH v2 0/5] Inspect reflog data programmatically in more tests Ævar Arnfjörð Bjarmason
2021-11-29 18:24 ` Han-Wen Nienhuys
2021-11-29 22:30 ` Junio C Hamano
2021-11-29 23:28 ` Ævar Arnfjörð Bjarmason
2021-12-02 16:11 ` Han-Wen Nienhuys
2021-12-02 17:36 ` [PATCH v3 " Han-Wen Nienhuys via GitGitGadget
2021-12-02 17:36 ` [PATCH v3 1/5] show-branch: show reflog message Han-Wen Nienhuys via GitGitGadget
2021-12-02 17:36 ` [PATCH v3 2/5] test-ref-store: don't add newline to " Han-Wen Nienhuys via GitGitGadget
2021-12-02 17:36 ` [PATCH v3 3/5] t1405: check for_each_reflog_ent_reverse() more thoroughly Han-Wen Nienhuys via GitGitGadget
2021-12-02 17:36 ` [PATCH v3 4/5] test-ref-store: tweaks to for-each-reflog-ent format Han-Wen Nienhuys via GitGitGadget
2021-12-02 17:36 ` [PATCH v3 5/5] refs/debug: trim trailing LF from reflog message Han-Wen Nienhuys via GitGitGadget
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=211129.86h7bvgvqt.gmgdl@evledraar.gmail.com \
--to=avarab@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitgitgadget@gmail.com \
--cc=gitster@pobox.com \
--cc=hanwen@google.com \
--cc=hanwenn@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).