From: Chinmoy Chakraborty Date: Tue, 30 Mar 2021 16:38:08 GMT Subject: Re: [PATCH v2] Documentation: updated documentation for git commit --date Message-ID: In-Reply-To: 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.