Documentation: updated documentation for git commit --date
PATCH 1/1 Documentation: updated documentation for git commit --date
From: Chinmoy Chakraborty <[email protected]>
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.
---
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.
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(-)
Documentation/date-formats.txt +32 -0
@@ -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 `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` environment variables support the following date formats:
Documentation/git-commit.txt +4 -1
@@ -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>>). -m <msg>:: --message=<msg>::
base-commit: 84d06cdc06389ae7c462434cb7b1db0980f63860
Signature · 1 line
gitgitgadget
PATCH v2 1/1 Documentation: updated documentation for git commit --date
From: Chinmoy Chakraborty <[email protected]>
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.
---
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.
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(-)
Documentation/date-formats.txt +32 -0
@@ -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 `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` environment variables support the following date formats:
Documentation/git-commit.txt +4 -1
@@ -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>>). -m <msg>:: --message=<msg>::
base-commit: 84d06cdc06389ae7c462434cb7b1db0980f63860
Signature · 1 line
gitgitgadget
Quoted 8 lines · Chinmoy via GitGitGadget
From: Chinmoy Chakraborty <[email protected]>
This commit lists the special strings used with
--dateingit-commit.txtand also a brief explanation about the strings indate-formats.txt.Signed-off-by Chinmoy Chakraborty <[email protected]>---
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?
Documentation/date-formats.txt line 21
Quoted 5 lines
+
tea::Documentation/date-formats.txt +4
-0+ 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?
Signature · 1 line
An old man doll... just what I always wanted! - Clara
Quoted 3 lines · Bagas Sanjaya
Is date format parsing specific to git commit? If so, then why not date-formats.txt be merged to
DATE FORMATSsection of git-commit documentation?
It is already included below the COMMIT INFORMATION section.
Quoted 2 lines
Also, what commit this
--date
option first appeared before you write this documentation?
I guess it was introduced in commit a8aca418d6484400d6804e22717bd49ca06c28e9.
Quoted 8 lines
Quoted 6 lines
+
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
Quoted 6 lines · Chinmoy Chakraborty
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:
Quoted 5 lines
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?
Signature · 1 line
An old man doll... just what I always wanted! - Clara
Quoted 3 lines · Bagas Sanjaya
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
Quoted 5 lines · Chinmoy via GitGitGadget
From: Chinmoy Chakraborty <[email protected]>
This commit lists the special strings used with
--dateingit-commit.txtand also a brief explanation about the strings indate-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.
Quoted 29 lines
Documentation/date-formats.txt +21
-0@@ -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
Documentation/date-formats.txt line 34
Quoted 10 lines
Documentation/date-formats.txt +10
-0+ 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*].
Quoted 8 lines
Documentation/date-formats.txt +0
-0The `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` environment variables support the following date formats:Documentation/git-commit.txt +0
-0
Documentation/git-commit.txt See linkgit:git-rebase[1] for details. · line 182
Quoted 8 lines
Documentation/git-commit.txt +4
-1@@ -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.
Quoted 11 lines · Junio C Hamano
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.
Quoted 9 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--dateoption 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[]
Quoted 6 lines
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'
Quoted 3 lines
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.
Quoted 9 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.
Quoted 4 lines
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.
Quoted 8 lines · Chinmoy Chakraborty
Quoted 8 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.
Quoted 8 lines
Quoted 4 lines
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.