doc: `--date` in `git-commit` accepts approxidates

Commit Message

Utku Feb. 23, 2021, 5:35 p.m. UTC

From: Utku Gultopu <[e-mail]>

Document the fact that the `--date` option in `git-commit` accepts any
date format that is accepted by the `approxidate_careful` function,
which is located in `date.c`.

Signed-off-by: Utku Gultopu <[e-mail]>
---
    doc: --date in git-commit accepts approxidates
    
    Without the documentation, it is kind of a "hidden feature", which I was
    able to discover only through online forums.
    
    I guess this patch is not ideal, because instead of properly
    documenting, it refers the user to the code. However I wasn't able to
    find documentation about the "approxidates" which I can link to. Please
    let me know how I can improve it.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-969%2Fugultopu%2Fdocument-approxidates-for-date-argument-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-969/ugultopu/document-approxidates-for-date-argument-v1
Pull-Request: https://github.com/git/git/pull/969

 Documentation/date-formats.txt | 9 +++------
 Documentation/git-commit.txt   | 4 +++-
 2 files changed, 6 insertions(+), 7 deletions(-)


base-commit: 966e671106b2fd38301e7c344c754fd118d0bb07

Comments

Jeff King Feb. 23, 2021, 6:11 p.m. UTC | #1

On Tue, Feb 23, 2021 at 05:35:46PM +0000, Utku Gultopu via GitGitGadget wrote:

> From: Utku Gultopu <[e-mail]>
> 
> Document the fact that the `--date` option in `git-commit` accepts any
> date format that is accepted by the `approxidate_careful` function,
> which is located in `date.c`.

I agree it's worth documenting this a bit better, but...

>     I guess this patch is not ideal, because instead of properly
>     documenting, it refers the user to the code. However I wasn't able to
>     find documentation about the "approxidates" which I can link to. Please
>     let me know how I can improve it.

...yeah. I don't think the phrase "approxidate_careful" is really
meaningful to end users.

Perhaps we can leave this hunk intact:

> +DATE FORMATS[[DATES]]
> +---------------------
>  
> -The `GIT_AUTHOR_DATE`, `GIT_COMMITTER_DATE` environment variables
> -ifdef::git-commit[]
> -and the `--date` option
> -endif::git-commit[]
> +The `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` environment variables
>  support the following date formats:

since it's true that --date does accept those formats.

And then at the end of that section, expand what it's willing to take:

ifdef::git-commit[]
The `--date` option (but not the environment variables) will also try to
make sense of other more human-centric date formats, including relative
dates like "yesterday" or "last Friday at noon".
endif::git-commit[]

-Peff

Junio C Hamano Feb. 23, 2021, 7:33 p.m. UTC | #2

Jeff King <[e-mail]> writes:

> And then at the end of that section, expand what it's willing to take:
>
> ifdef::git-commit[]
> The `--date` option (but not the environment variables) will also try to
> make sense of other more human-centric date formats, including relative
> dates like "yesterday" or "last Friday at noon".
> endif::git-commit[]

Yup, I find this a lot more acceptable than reference to the code
that may happen to be correct only at this moment but can deviate
over time from the reality.  IIRC, the implementation detail cited
in the patch under review (e.g. use of _careful() helper) did change
in 2014.

Thanks, both.  Looking forward to seeing an updated patch.

Patch

diff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt
index f1097fac69a6..8332f592e252 100644
--- a/Documentation/date-formats.txt
+++ b/Documentation/date-formats.txt
@@ -1,10 +1,7 @@ 
-DATE FORMATS
-------------
+DATE FORMATS[[DATES]]
+---------------------
 
-The `GIT_AUTHOR_DATE`, `GIT_COMMITTER_DATE` environment variables
-ifdef::git-commit[]
-and the `--date` option
-endif::git-commit[]
+The `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` environment variables
 support the following date formats:
 
 Git internal format::
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 17150fa7eabe..b96b7715a0a8 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -143,7 +143,9 @@  OPTIONS
 	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 '<date>' can be in
+	any format that is accepted by the `approxidate_careful` function
+	in `date.c` or the <<DATES, DATE FORMATS>> section below.
 
 -m <msg>::
 --message=<msg>::