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

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(-)

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

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

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

Perhaps we can leave this hunk intact:

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

Jeff King <peff@peff.net> writes:

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.

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(-)

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

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

Jeff King <peff@peff.net> writes:

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.

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

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

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(-)

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.