"Chinmoy via GitGitGadget" <gitgitgadget@xxxxxxxxx> writes:
> From: Chinmoy Chakraborty <chinmoy12c@xxxxxxxxx>
>
> 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.
