| Message ID | pull.969.v2.git.git.1614106322760.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v2] doc: `--date` in `git-commit` accepts approxidates | expand |
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
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.
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.
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 <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[]
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[]