archive mirror
 help / color / mirror / Atom feed
From: Chinmoy Chakraborty <>
Subject: Re: [PATCH v2] Documentation: updated documentation for git commit --date
Date: Tue, 30 Mar 2021 22:08:08 +0530	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <xmqqim59irba.fsf@gitster.g>

On 3/30/21 2:57 AM, Junio C Hamano wrote:
> All of that can be read from the patch text.  What an author is
> expected to explain in the proposed commit log message is WHY.
> Why is it a good idea to list possible arguments --date can take?
> The reason can include "because so far they are not explained
> anywhere."
> Documentation/SubmittingPatches::describe-changes, especially
> [[meaningful-message]], is a good source to learn what a title and a
> proposed log message of a patch should look like in this project.

Okay I'll update the patch with proper commit message.

> I am not very strongly opposed to extending the tail end of the
> existing contents of the file, namely:
>      ifdef::git-commit[]
>      In addition to recognizing all date formats above, the `--date` option
>      will also try to make sense of other, more human-centric date formats,
>      such as relative dates like "yesterday" or "last Friday at noon".
>      endif::git-commit[]
> and explain what "such as ..." is, but I am fairly negative on
> teaching 'tea' to our users before we talk about 2822 and 8601
> formats.  I actually think the above three lines strikes a good
> balance---we do not want the users to be surprised too much when
> they see "--date yesterday" to work, but we do not particularly
> want to encourage them to use "commit --date noon" [*1*].

Okay so I guess it's better to just extend the tail of the file

to explain a little bit about the relative dates and leave

out the Easter eggs and formats like 'noon' and 'midnight'

> Likewise.  I am OK with adding (see date-formats) but against
> listing the easter eggs as if they are more important than other
> forms.

Okay I'll just add the (see date-formats) and leave out the

exhaustive list.

> [Footnote]
> *1* The approxidate is useful when a rough "around that time"
>      specification suffices, e.g. "git log --since='last.week'".  The
>      user is OK to see commits down to roughly a week old, and would
>      not be upset if a commit with a timestamp that is 9 days old
>      shown.
>      On the other hand, it would be unusual that somebody cares
>      enough to use "git commit --date" but yet it is OK that the time
>      recorded is fuzzy.  For that reason alone, I am in general
>      negative on the direction this patch tries to take us in.

So according to you, is it a relevant/worthwhile change

to add in docs?


  reply	other threads:[~2021-03-30 16:37 UTC|newest]

Thread overview: 9+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-03-28 10:19 [PATCH] Documentation: updated documentation for git commit --date Chinmoy via GitGitGadget
2021-03-28 12:54 ` [PATCH v2] " Chinmoy via GitGitGadget
2021-03-29  5:25   ` Bagas Sanjaya
2021-03-29  6:02     ` Chinmoy Chakraborty
2021-03-29 11:11       ` Bagas Sanjaya
2021-03-29 14:56         ` Chinmoy Chakraborty
2021-03-29 21:27   ` Junio C Hamano
2021-03-30 16:38     ` Chinmoy Chakraborty [this message]
2021-03-30 17:28       ` Junio C Hamano

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:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \

* 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.
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 NNTP newsgroup(s).