Re: [PATCH v2] Documentation: updated documentation for git commit --date
On 3/30/21 2:57 AM, Junio C Hamano wrote:
Show 11 quoted lines
> 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.
Show 15 quoted lines
> 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.
Show 13 quoted lines
>
> [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.
Chinmoy Chakraborty <chinmoy12c@gmail.com>