doc: `--date` in `git-commit` accepts approxidates
PATCH 1/1 doc: `--date` in `git-commit` accepts approxidates
From: Utku Gultopu <[email protected]>
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.
---
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(-)
Documentation/date-formats.txt +3 -6
@@ -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::
Documentation/git-commit.txt +3 -1
@@ -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
Signature · 1 line
gitgitgadget
Quoted 5 lines · Utku Gultopu via GitGitGadget
From: Utku Gultopu <[email protected]>
Document the fact that the
--dateoption ingit-commitaccepts any date format that is accepted by theapproxidate_carefulfunction, which is located indate.c.
I agree it's worth documenting this a bit better, but...
Quoted 4 lines
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:
Documentation/date-formats.txt line 5
Quoted 9 lines
Documentation/date-formats.txt +3
-4+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
Quoted 7 lines · Jeff King
And then at the end of that section, expand what it's willing to take:
ifdef::git-commit[]
The--dateoption (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 v2 1/1 doc: `--date` in `git-commit` accepts approxidates
In reply to Utku Gultopu via GitGitGadgetFrom: Utku Gultopu <[email protected]>
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.
---
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(-)
Documentation/date-formats.txt +9 -4
@@ -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
Signature · 1 line
gitgitgadget
Documentation/date-formats.txt ISO 8601:: · line 33
Quoted 7 lines · Utku Gultopu via GitGitGadget
Documentation/date-formats.txt +7
-0+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
A message that is not in the archive (sent off-list or not yet received): CAEeqB6kqZTft9NWtOvm3hk9bicBL7GU_WYuAGdMG1MHYMgNAxg@mail.gmail.com
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.
Quoted 14 lines · Jeff King
Documentation/date-formats.txt ISO 8601:: · line 33
Quoted 7 lines · Utku Gultopu via GitGitGadget
Documentation/date-formats.txt +7
-0+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. :)
Quoted 3 lines
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.
Quoted 2 lines · Utku
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.
--- Documentation/date-formats.txt | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-)
Documentation/date-formats.txt +7 -4
@@ -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[]
Signature · 1 line
2.30.1.1095.g03347429ea