git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Junio C Hamano <gitster@pobox.com>
To: "Chinmoy via GitGitGadget" <gitgitgadget@gmail.com>
Cc: git@vger.kernel.org, Chinmoy <chinmoy12c@gmail.com>
Subject: Re: [PATCH v2] Documentation: updated documentation for git commit --date
Date: Mon, 29 Mar 2021 14:27:21 -0700	[thread overview]
Message-ID: <xmqqim59irba.fsf@gitster.g> (raw)
In-Reply-To: <pull.918.v2.git.1616936099778.gitgitgadget@gmail.com> (Chinmoy via GitGitGadget's message of "Sun, 28 Mar 2021 12:54:59 +0000")

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




  parent reply	other threads:[~2021-03-29 21:28 UTC|newest]

Thread overview: 9+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-03-28 10:19 [PATCH] Documentation: updated documentation for git commit --date Chinmoy via GitGitGadget
2021-03-28 12:54 ` [PATCH v2] " Chinmoy via GitGitGadget
2021-03-29  5:25   ` Bagas Sanjaya
2021-03-29  6:02     ` Chinmoy Chakraborty
2021-03-29 11:11       ` Bagas Sanjaya
2021-03-29 14:56         ` Chinmoy Chakraborty
2021-03-29 21:27   ` Junio C Hamano [this message]
2021-03-30 16:38     ` Chinmoy Chakraborty
2021-03-30 17:28       ` Junio C Hamano

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=xmqqim59irba.fsf@gitster.g \
    --to=gitster@pobox.com \
    --cc=chinmoy12c@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitgitgadget@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).