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

Jeff King [off-list ref] writes:

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

quoted

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

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:

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 [off-list ref]
Signed-off-by: Jeff King <redacted>
---
 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