Re: [PATCH v2] Documentation: updated documentation for git commit --date

[Chinmoy Chakraborty <chinmoy12c@gmail.com>]

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?


Thanks.