From: Utku Gultopu via GitGitGadget <hidden> Date: 2021-02-23 17:36:39
From: Utku Gultopu <redacted>
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 <redacted>
---
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(-)
@@ -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::
@@ -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>::
From: Jeff King <hidden> Date: 2021-02-23 18:12:35
On Tue, Feb 23, 2021 at 05:35:46PM +0000, Utku Gultopu via GitGitGadget wrote:
From: Utku Gultopu <redacted>
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
From: Utku Gultopu via GitGitGadget <hidden> Date: 2021-02-23 18:53:17
From: Utku Gultopu <redacted>
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 <redacted>
---
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(-)
@@ -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[]
From: Jeff King <hidden> Date: 2021-02-23 19:06:51
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