Documentation: updated documentation for git commit --date

[chinmoy12c]

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

cc: Bagas Sanjaya bagasdotme@gmail.com

cc: Bagas Sanjaya bagasdotme@gmail.com

[chinmoy12c]

Hey @dscho, I'm having some problem linking the date-formats.txt. Could you please tell me how to properly link the file?

[dscho]

Hey @dscho, I'm having some problem linking the date-formats.txt. Could you please tell me how to properly link the file?

The date-formats.txt file is not actually compiled into a manual page. Instead, it is included (e.g. in git-commit.txt). That is, there is no need to link, you can just refer to the section.

The common way to reference sections seems to be to use <<DATE FORMATS>>. See e.g.

git/Documentation/git-config.txt

Line 40 in ecf4fe0

prepend a single exclamation mark in front (see also <<EXAMPLES>>),

which refers to

git/Documentation/git-config.txt

Line 366 in ecf4fe0

[[EXAMPLES]]

.

[chinmoy12c]

Hey @dscho, I'm having some problem linking the date-formats.txt. Could you please tell me how to properly link the file?

The date-formats.txt file is not actually compiled into a manual page. Instead, it is included (e.g. in git-commit.txt). That is, there is no need to link, you can just refer to the section.

The common way to reference sections seems to be to use <<DATE FORMATS>>. See e.g.

git/Documentation/git-config.txt

Line 40 in ecf4fe0

prepend a single exclamation mark in front (see also <<EXAMPLES>>),

which refers to

git/Documentation/git-config.txt

Line 366 in ecf4fe0

[[EXAMPLES]]

.

Okay thanks :)

[chinmoy12c]

/submit

[gitgitgadget]

Submitted as pull.918.git.1616926790227.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git pr-918/chinmoy12c/issue_302-v1

To fetch this version to local tag pr-918/chinmoy12c/issue_302-v1:

git fetch --no-tags https://github.com/gitgitgadget/git tag pr-918/chinmoy12c/issue_302-v1

[chinmoy12c]

/submit

[gitgitgadget]

Submitted as pull.918.v2.git.1616936099778.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git pr-918/chinmoy12c/issue_302-v2

To fetch this version to local tag pr-918/chinmoy12c/issue_302-v2:

git fetch --no-tags https://github.com/gitgitgadget/git tag pr-918/chinmoy12c/issue_302-v2

[gitgitgadget]

On the Git mailing list, Bagas Sanjaya wrote (reply to this):

On 28/03/21 19.54, Chinmoy via GitGitGadget wrote:
> 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>
> ---
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?

> +`tea`::
> +	Change commit time to 17:00(tea time). If the current
> +	time is less than 17:00, the time will be set to 17:00
> +	on the previous day, else it will be set to 17:00 on
> +	the same day.
How useful is this argument?

-- 
An old man doll... just what I always wanted! - Clara

[gitgitgadget]

User Bagas Sanjaya <bagasdotme@gmail.com> has been added to the cc: list.

[gitgitgadget]

On the Git mailing list, Chinmoy Chakraborty wrote (reply to this):

On 3/29/21 10:55 AM, Bagas Sanjaya 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?
It is already included below the `COMMIT INFORMATION` section.

> Also, what commit this `--date`
> option first appeared before you write this documentation?

I guess it was introduced in commit 
a8aca418d6484400d6804e22717bd49ca06c28e9.

>
>> +`tea`::
>> +    Change commit time to 17:00(tea time). If the current
>> +    time is less than 17:00, the time will be set to 17:00
>> +    on the previous day, else it will be set to 17:00 on
>> +    the same day.
> How useful is this argument?
>
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

[gitgitgadget]

On the Git mailing list, Bagas Sanjaya wrote (reply to this):

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

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

The commit you mentioned (a8aca418d6484400d6804e22717bd49ca06c28e9)
said that:

>     Thanks for pointing out tea-time.
> 
>     This is also written to easily extended to allow people to add their own
>     important dates like Christmas and their own birthdays.
> 

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?

-- 
An old man doll... just what I always wanted! - Clara

[gitgitgadget]

User Bagas Sanjaya <bagasdotme@gmail.com> has been added to the cc: list.

[gitgitgadget]

On the Git mailing list, Chinmoy Chakraborty wrote (reply to this):

On 3/29/21 4:41 PM, Bagas Sanjaya wrote:
>
> Also, I asked to you: can I set --date to arbitrary date (like 09/29/2009
> 19:59)?


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

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

[gitgitgadget]

On the Git mailing list, Junio C Hamano wrote (reply to this):

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

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

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.

> diff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt
> index 99c455f51c04..83c423a3ec2e 100644
> --- a/Documentation/date-formats.txt
> +++ b/Documentation/date-formats.txt
> @@ -1,6 +1,38 @@
> +[[DATE-FORMATS]]
>  DATE FORMATS
>  ------------
>  
> +`yesterday`::
> +	Change commit time to yesterday, that is, 24 hours ago.
> +
> +`noon`::
> +	Change commit time to noon, that is 12:00. If current
> +	time is less than 12:00, the time will be set to 12:00
> +	on the previous day, else it will be set to 12:00 on
> +	the same day.
> +
> +`midnight`::
> +	Change commit time to midnight, that is, 00:00.
> +
> +`tea`::
> +	Change commit time to 17:00(tea time). If the current
> +	time is less than 17:00, the time will be set to 17:00
> +	on the previous day, else it will be set to 17:00 on
> +	the same day.
> +
> +`PM`::
> +	Change commit time from AM to PM. If the current time
> +	is already greater than 12:00, then the time remains
> +	unaltered.
> +
> +`AM`::
> +	Change commit time from PM to AM. If current time is
> +	already less than 12:00, then the time remains
> +	unaltered.
> +
> +`now`::
> +	Change commit time to current time.

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

>  The `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` environment variables
>  support the following date formats:
>  
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index 3c69f461c9af..1935fad33f35 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -176,7 +176,10 @@ See linkgit:git-rebase[1] for details.
>  	the commit author is then copied from the first such commit found.
>  
>  --date=<date>::
> -	Override the author date used in the commit.
> +	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>>).

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.

[gitgitgadget]

On the Git mailing list, Chinmoy Chakraborty wrote (reply to this):

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.

[gitgitgadget]

On the Git mailing list, Junio C Hamano wrote (reply to this):

Chinmoy Chakraborty <chinmoy12c@gmail.com> writes:

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

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.

[dscho]

@chinmoy12c what's the state of this?