patchDocumentation: updated documentation for git commit --date

From: Chinmoy Chakraborty <chinmoy12c@gmail.com>

This commit lists the special strings used with `--date` in `git-commit.txt` and also a brief explanation about the strings in `date-formats.txt`.

Signed-off-by: Chinmoy Chakraborty <chinmoy12c@gmail.com>
---
    Documentation: updated documentation for git commit --date
    
    This commit lists the special strings used with --date in git-commit.txt
    and also a brief explanation about the strings in date-formats.txt.
    
    Signed-off-by: Chinmoy Chakraborty chinmoy12c@gmail.com
    
    
    Related Issue
    =============
    
    #302

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-918%2Fchinmoy12c%2Fissue_302-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-918/chinmoy12c/issue_302-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/918

 Documentation/date-formats.txt | 32 ++++++++++++++++++++++++++++++++
 Documentation/git-commit.txt   |  5 ++++-
 2 files changed, 36 insertions(+), 1 deletion(-)

From: Chinmoy Chakraborty <chinmoy12c@gmail.com>

This commit lists the special strings used with `--date` in `git-commit.txt` and also a brief explanation about the strings in `date-formats.txt`.

Signed-off-by: Chinmoy Chakraborty <chinmoy12c@gmail.com>
---
    Documentation: updated documentation for git commit --date
    
    This commit lists the special strings used with --date in git-commit.txt
    and also a brief explanation about the strings in date-formats.txt.
    
    Signed-off-by: Chinmoy Chakraborty chinmoy12c@gmail.com
    
    
    Related Issue
    =============
    
    #302

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-918%2Fchinmoy12c%2Fissue_302-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-918/chinmoy12c/issue_302-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/918

Range-diff vs v1:

 1:  818ac39b5203 ! 1:  20da93dea971 Documentation: updated documentation for git commit --date
     @@ Commit message
      
       ## Documentation/date-formats.txt ##
      @@
     -+[[DATE FORMATS]]
     ++[[DATE-FORMATS]]
       DATE FORMATS
       ------------
       
     @@ Documentation/git-commit.txt: See linkgit:git-rebase[1] for details.
      +	Override the author date used in the commit. The value of <date>
      +	may be any one of the following special values - "yesterday",
      +	"noon", "midnight", "tea", "PM", "AM", "never", "now"
     -+	(see <<DATE FORMATS>>).
     ++	(see <<DATE-FORMATS>>).
       
       -m <msg>::
       --message=<msg>::

 Documentation/date-formats.txt | 32 ++++++++++++++++++++++++++++++++
 Documentation/git-commit.txt   |  5 ++++-
 2 files changed, 36 insertions(+), 1 deletion(-)

On 28/03/21 19.54, Chinmoy via GitGitGadget wrote:

Is date format parsing specific to git commit? If so, then why not date-formats.txt be merged to `DATE FORMATS` section of git-commit documentation? Also, what commit this `--date` option first appeared before you write this documentation?

How useful is this argument?

On 3/29/21 10:55 AM, Bagas Sanjaya wrote:

It is already included below the `COMMIT INFORMATION` section.

I guess it was introduced in commit a8aca418d6484400d6804e22717bd49ca06c28e9.

I think initially it was suggested as a joke, but actually implemented

to demonstrate the ability for users to include their own custom

time/date periods.

See : https://github.com/git/git/commit/a8aca418d6484400d6804e22717bd49ca06c28e9

On 29/03/21 13.02, Chinmoy Chakraborty wrote:

Hmmm...

The commit you mentioned (a8aca418d6484400d6804e22717bd49ca06c28e9) said that:

But it seems like the predefined dates/times were hard-coded, so to extend --date option to allow more predefined date/times, Git sources need to be edited.

Maybe we can make git config option (commit.predefined_times [FIXME: suggest better name]) so user can easily add ones.

Also, I asked to you: can I set --date to arbitrary date (like 09/29/2009 19:59)?

[CC] Junio, what about this patch?

On 3/29/21 4:41 PM, Bagas Sanjaya wrote:

Sure you can use something like git commit --date='2009-09-29 19:59:00'

or git commit --date=`2 days ago`

"Chinmoy via GitGitGadget" <gitgitgadget@gmail.com> writes:

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.

The "commit" related documentation is not the only consumer of this file. These new descriptions repeatedly stress "commit time", but are these acceptable to readers of other page(s) that include this file, or is the discrepancy irritating to them?

In any case, I personally think these should NOT be described at the beginning of this file. The primary formats the end-users should learn to use are the ones that are described already in the document. All of the above are more like "by the way, did you know that 'git-commit --date' takes these cute strings? easter eggs.

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*].

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

Thanks.

[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.

On 3/30/21 2:57 AM, Junio C Hamano wrote:

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

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'

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

exhaustive list.

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

to add in docs?

Thanks.

Chinmoy Chakraborty <chinmoy12c@gmail.com> writes:

That depends on the "docs".

If we do not hint that relative dates are also usable, in addition to the more common date formats like RFC2822 and ISO8601, for "log --since" and other options that are used to specify a boundary for looking up existing things, extending their documentation may be worth doing.

Giving 'tea' and other oddities at the top as if they are more important than the formats that is used to give more precise input for options that are used to specify what timestamp is recorded in an object the command is about to create would be a change with negative value.

Thanks.