[PATCH] doc: `--date` in `git-commit` accepts approxidates

[PATCH] doc: `--date` in `git-commit` accepts approxidates

[Utku Gultopu via GitGitGadget]

From: Utku Gultopu <ugultopu@gmail.com>

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 <ugultopu@gmail.com>
---
    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(-)

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>::

base-commit: 966e671106b2fd38301e7c344c754fd118d0bb07
-- 
gitgitgadget

Re: [PATCH] doc: `--date` in `git-commit` accepts approxidates

[Jeff King]

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

> From: Utku Gultopu <ugultopu@gmail.com>
> 
> 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

[PATCH v2] doc: `--date` in `git-commit` accepts approxidates

[Utku Gultopu via GitGitGadget]

From: Utku Gultopu <ugultopu@gmail.com>

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 <ugultopu@gmail.com>
---
    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-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-969/ugultopu/document-approxidates-for-date-argument-v2
Pull-Request: https://github.com/git/git/pull/969

Range-diff vs v1:

 1:  9116ad67a0c6 ! 1:  e564d7d9af3d doc: `--date` in `git-commit` accepts approxidates
     @@ Commit message
      
       ## Documentation/date-formats.txt ##
      @@
     --DATE FORMATS
     --------------
     -+DATE FORMATS[[DATES]]
     -+---------------------
     + DATE FORMATS
     + ------------
       
      -The `GIT_AUTHOR_DATE`, `GIT_COMMITTER_DATE` environment variables
      -ifdef::git-commit[]
     @@ Documentation/date-formats.txt
       support the following date formats:
       
       Git internal format::
     -
     - ## Documentation/git-commit.txt ##
     -@@ Documentation/git-commit.txt: 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>::
     +@@ Documentation/date-formats.txt: ISO 8601::
     + +
     + NOTE: In addition, the date part is accepted in the following formats:
     + `YYYY.MM.DD`, `MM/DD/YYYY` and `DD.MM.YYYY`.
     ++
     ++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". For
     ++further details on what kind of formats are accepted, please refer to
     ++the `approxidate_careful` function in `date.c` file in Git source code.
     ++endif::git-commit[]


 Documentation/date-formats.txt | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt
index f1097fac69a6..b86a5a25fe46 100644
--- a/Documentation/date-formats.txt
+++ b/Documentation/date-formats.txt
@@ -1,10 +1,7 @@
 DATE FORMATS
 ------------
 
-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::
@@ -26,3 +23,11 @@ ISO 8601::
 +
 NOTE: In addition, the date part is accepted in the following formats:
 `YYYY.MM.DD`, `MM/DD/YYYY` and `DD.MM.YYYY`.
+
+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". For
+further details on what kind of formats are accepted, please refer to
+the `approxidate_careful` function in `date.c` file in Git source code.
+endif::git-commit[]

base-commit: 966e671106b2fd38301e7c344c754fd118d0bb07
-- 
gitgitgadget

Re: [PATCH v2] doc: `--date` in `git-commit` accepts approxidates

[Jeff King]

On Tue, Feb 23, 2021 at 06:52:02PM +0000, Utku Gultopu via GitGitGadget wrote:

> +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". For
> +further details on what kind of formats are accepted, please refer to
> +the `approxidate_careful` function in `date.c` file in Git source code.
> +endif::git-commit[]

OK. This is still referring to `approxidate_careful`, which may not be
meaningful to most users. But at least it makes a best effort at a
hand-waving definition before then. :)

I'd probably omit the final sentence entirely (as it may simply confuse
people who don't know how to find Git's source), but I'm OK with it
either way.

-Peff

Re: [PATCH v2] doc: `--date` in `git-commit` accepts approxidates

[Utku]

I thought it is good to refer the reader to _somewhere_ for
completeness, since those two examples do not cover all cases. Since
there is no documentation for it, I referred the reader to the code.

Re: [PATCH] doc: `--date` in `git-commit` accepts approxidates

[Junio C Hamano]

Jeff King <peff@peff.net> 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.

Re: [PATCH v2] doc: `--date` in `git-commit` accepts approxidates

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Tue, Feb 23, 2021 at 06:52:02PM +0000, Utku Gultopu via GitGitGadget wrote:
>
>> +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". For
>> +further details on what kind of formats are accepted, please refer to
>> +the `approxidate_careful` function in `date.c` file in Git source code.
>> +endif::git-commit[]
>
> OK. This is still referring to `approxidate_careful`, which may not be
> meaningful to most users. But at least it makes a best effort at a
> hand-waving definition before then. :)
>
> I'd probably omit the final sentence entirely (as it may simply confuse
> people who don't know how to find Git's source), but I'm OK with it
> either way.

I am not happy with reference to approxidate_careful that has no
place in end-user facing documentation.  I think the one you
suggested struck a better balance.

Re: [PATCH v2] doc: `--date` in `git-commit` accepts approxidates

[Utku]

In this case, maybe Jeff can submit a patch, since I wouldn't be adding
anything to what he suggested.

Re: [PATCH v2] doc: `--date` in `git-commit` accepts approxidates

[Jeff King]

On Tue, Feb 23, 2021 at 03:24:58PM -0500, Utku wrote:

> In this case, maybe Jeff can submit a patch, since I wouldn't be adding
> anything to what he suggested.

I'm happy to do that to move things along, though really 99% of the work
was in your initially identifying the problem. Here's what I would
suggest (I did steal your hunk to push all of the --date bits down into
that separate paragraph):

-- >8 --
Subject: [PATCH] doc: mention approxidates for git-commit --date

We describe the more strict date formats accepted by GIT_COMMITTER_DATE,
etc, but the --date option also allows the looser approxidate formats,
as well. Unfortunately we don't have a good or complete reference for
this format, but let's at least mention that it _is_ looser, and give a
few examples.

If we ever write separate, more complete date-format documentation, we
should refer to it from here.

Based-on-a-patch-by: Utku Gultopu <ugultopu@gmail.com>
Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/date-formats.txt | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt
index f1097fac69..99c455f51c 100644
--- a/Documentation/date-formats.txt
+++ b/Documentation/date-formats.txt
@@ -1,10 +1,7 @@
 DATE FORMATS
 ------------
 
-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::
@@ -26,3 +23,9 @@ ISO 8601::
 +
 NOTE: In addition, the date part is accepted in the following formats:
 `YYYY.MM.DD`, `MM/DD/YYYY` and `DD.MM.YYYY`.
+
+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[]
-- 
2.30.1.1095.g03347429ea