{"thread":{"id":"55194","subject":"[PATCH] doc: `--date` in `git-commit` accepts approxidates","startedAt":"2021-02-23T17:36:39Z","lastAt":"2021-02-23T20:52:15Z","messageCount":9,"participants":["Utku Gultopu via GitGitGadget","Jeff King","Utku","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"417570","messageId":"pull.969.git.git.1614101746491.gitgitgadget@gmail.com","threadId":"55194","inReplyTo":null,"subject":"[PATCH] doc: `--date` in `git-commit` accepts approxidates","fromName":"Utku Gultopu via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2021-02-23T17:35:46Z","receivedAt":"2021-02-23T17:36:39Z","isPatch":true,"sender":{"key":"name:Utku Gultopu","avatar":null},"body":"From: Utku Gultopu \n\nDocument the fact that the `--date` option in `git-commit` accepts any\ndate format that is accepted by the `approxidate_careful` function,\nwhich is located in `date.c`.\n\nSigned-off-by: Utku Gultopu \n---\n doc: --date in git-commit accepts approxidates\n \n Without the documentation, it is kind of a \"hidden feature\", which I was\n able to discover only through online forums.\n \n I guess this patch is not ideal, because instead of properly\n documenting, it refers the user to the code. However I wasn't able to\n find documentation about the \"approxidates\" which I can link to. Please\n let me know how I can improve it.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-969%2Fugultopu%2Fdocument-approxidates-for-date-argument-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-969/ugultopu/document-approxidates-for-date-argument-v1\nPull-Request: https://github.com/git/git/pull/969\n\n Documentation/date-formats.txt | 9 +++------\n Documentation/git-commit.txt | 4 +++-\n 2 files changed, 6 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt\nindex f1097fac69a6..8332f592e252 100644\n--- a/Documentation/date-formats.txt\n+++ b/Documentation/date-formats.txt\n@@ -1,10 +1,7 @@\n-DATE FORMATS\n-------------\n+DATE FORMATS[[DATES]]\n+---------------------\n \n-The `GIT_AUTHOR_DATE`, `GIT_COMMITTER_DATE` environment variables\n-ifdef::git-commit[]\n-and the `--date` option\n-endif::git-commit[]\n+The `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` environment variables\n support the following date formats:\n \n Git internal format::\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 17150fa7eabe..b96b7715a0a8 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -143,7 +143,9 @@ OPTIONS\n \tthe commit author is then copied from the first such commit found.\n \n --date=::\n-\tOverride the author date used in the commit.\n+\tOverride the author date used in the commit. The '' can be in\n+\tany format that is accepted by the `approxidate_careful` function\n+\tin `date.c` or the <> section below.\n \n -m ::\n --message=::\n\nbase-commit: 966e671106b2fd38301e7c344c754fd118d0bb07\n-- \ngitgitgadget\n"},{"id":"417572","messageId":"YDVFaTGnPCfuJQSa@coredump.intra.peff.net","threadId":"55194","inReplyTo":"pull.969.git.git.1614101746491.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: `--date` in `git-commit` accepts approxidates","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-02-23T18:11:53Z","receivedAt":"2021-02-23T18:12:35Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Feb 23, 2021 at 05:35:46PM +0000, Utku Gultopu via GitGitGadget wrote:\n\n> From: Utku Gultopu \n> \n> Document the fact that the `--date` option in `git-commit` accepts any\n> date format that is accepted by the `approxidate_careful` function,\n> which is located in `date.c`.\n\nI agree it's worth documenting this a bit better, but...\n\n> I guess this patch is not ideal, because instead of properly\n> documenting, it refers the user to the code. However I wasn't able to\n> find documentation about the \"approxidates\" which I can link to. Please\n> let me know how I can improve it.\n\n...yeah. I don't think the phrase \"approxidate_careful\" is really\nmeaningful to end users.\n\nPerhaps we can leave this hunk intact:\n\n> +DATE FORMATS[[DATES]]\n> +---------------------\n> \n> -The `GIT_AUTHOR_DATE`, `GIT_COMMITTER_DATE` environment variables\n> -ifdef::git-commit[]\n> -and the `--date` option\n> -endif::git-commit[]\n> +The `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` environment variables\n> support the following date formats:\n\nsince it's true that --date does accept those formats.\n\nAnd then at the end of that section, expand what it's willing to take:\n\nifdef::git-commit[]\nThe `--date` option (but not the environment variables) will also try to\nmake sense of other more human-centric date formats, including relative\ndates like \"yesterday\" or \"last Friday at noon\".\nendif::git-commit[]\n\n-Peff\n"},{"id":"417579","messageId":"pull.969.v2.git.git.1614106322760.gitgitgadget@gmail.com","threadId":"55194","inReplyTo":"pull.969.git.git.1614101746491.gitgitgadget@gmail.com","subject":"[PATCH v2] doc: `--date` in `git-commit` accepts approxidates","fromName":"Utku Gultopu via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2021-02-23T18:52:02Z","receivedAt":"2021-02-23T18:53:17Z","isPatch":true,"sender":{"key":"name:Utku Gultopu","avatar":null},"body":"From: Utku Gultopu \n\nDocument the fact that the `--date` option in `git-commit` accepts any\ndate format that is accepted by the `approxidate_careful` function,\nwhich is located in `date.c`.\n\nSigned-off-by: Utku Gultopu \n---\n doc: --date in git-commit accepts approxidates\n \n Without the documentation, it is kind of a \"hidden feature\", which I was\n able to discover only through online forums.\n \n I guess this patch is not ideal, because instead of properly\n documenting, it refers the user to the code. However I wasn't able to\n find documentation about the \"approxidates\" which I can link to. Please\n let me know how I can improve it.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-969%2Fugultopu%2Fdocument-approxidates-for-date-argument-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-969/ugultopu/document-approxidates-for-date-argument-v2\nPull-Request: https://github.com/git/git/pull/969\n\nRange-diff vs v1:\n\n 1: 9116ad67a0c6 ! 1: e564d7d9af3d doc: `--date` in `git-commit` accepts approxidates\n @@ Commit message\n \n ## Documentation/date-formats.txt ##\n @@\n --DATE FORMATS\n --------------\n -+DATE FORMATS[[DATES]]\n -+---------------------\n + DATE FORMATS\n + ------------\n \n -The `GIT_AUTHOR_DATE`, `GIT_COMMITTER_DATE` environment variables\n -ifdef::git-commit[]\n @@ Documentation/date-formats.txt\n support the following date formats:\n \n Git internal format::\n -\n - ## Documentation/git-commit.txt ##\n -@@ Documentation/git-commit.txt: OPTIONS\n - \tthe commit author is then copied from the first such commit found.\n - \n - --date=::\n --\tOverride the author date used in the commit.\n -+\tOverride the author date used in the commit. The '' can be in\n -+\tany format that is accepted by the `approxidate_careful` function\n -+\tin `date.c` or the <> section below.\n - \n - -m ::\n - --message=::\n +@@ Documentation/date-formats.txt: ISO 8601::\n + +\n + NOTE: In addition, the date part is accepted in the following formats:\n + `YYYY.MM.DD`, `MM/DD/YYYY` and `DD.MM.YYYY`.\n ++\n ++ifdef::git-commit[]\n ++In addition to recognizing all date formats above, the `--date` option\n ++will also try to make sense of other, more human-centric date formats,\n ++such as relative dates like \"yesterday\" or \"last Friday at noon\". For\n ++further details on what kind of formats are accepted, please refer to\n ++the `approxidate_careful` function in `date.c` file in Git source code.\n ++endif::git-commit[]\n\n\n Documentation/date-formats.txt | 13 +++++++++----\n 1 file changed, 9 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt\nindex f1097fac69a6..b86a5a25fe46 100644\n--- a/Documentation/date-formats.txt\n+++ b/Documentation/date-formats.txt\n@@ -1,10 +1,7 @@\n DATE FORMATS\n ------------\n \n-The `GIT_AUTHOR_DATE`, `GIT_COMMITTER_DATE` environment variables\n-ifdef::git-commit[]\n-and the `--date` option\n-endif::git-commit[]\n+The `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` environment variables\n support the following date formats:\n \n Git internal format::\n@@ -26,3 +23,11 @@ ISO 8601::\n +\n NOTE: In addition, the date part is accepted in the following formats:\n `YYYY.MM.DD`, `MM/DD/YYYY` and `DD.MM.YYYY`.\n+\n+ifdef::git-commit[]\n+In addition to recognizing all date formats above, the `--date` option\n+will also try to make sense of other, more human-centric date formats,\n+such as relative dates like \"yesterday\" or \"last Friday at noon\". For\n+further details on what kind of formats are accepted, please refer to\n+the `approxidate_careful` function in `date.c` file in Git source code.\n+endif::git-commit[]\n\nbase-commit: 966e671106b2fd38301e7c344c754fd118d0bb07\n-- \ngitgitgadget\n"},{"id":"417581","messageId":"YDVSICgBwPLtDNu4@coredump.intra.peff.net","threadId":"55194","inReplyTo":"pull.969.v2.git.git.1614106322760.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] doc: `--date` in `git-commit` accepts approxidates","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-02-23T19:06:08Z","receivedAt":"2021-02-23T19:06:51Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Feb 23, 2021 at 06:52:02PM +0000, Utku Gultopu via GitGitGadget wrote:\n\n> +ifdef::git-commit[]\n> +In addition to recognizing all date formats above, the `--date` option\n> +will also try to make sense of other, more human-centric date formats,\n> +such as relative dates like \"yesterday\" or \"last Friday at noon\". For\n> +further details on what kind of formats are accepted, please refer to\n> +the `approxidate_careful` function in `date.c` file in Git source code.\n> +endif::git-commit[]\n\nOK. This is still referring to `approxidate_careful`, which may not be\nmeaningful to most users. But at least it makes a best effort at a\nhand-waving definition before then. :)\n\nI'd probably omit the final sentence entirely (as it may simply confuse\npeople who don't know how to find Git's source), but I'm OK with it\neither way.\n\n-Peff\n"},{"id":"417583","messageId":"92F10D2F-839A-440E-AECD-99D383409785@gmail.com","threadId":"55194","inReplyTo":"CAEeqB6kqZTft9NWtOvm3hk9bicBL7GU_WYuAGdMG1MHYMgNAxg@mail.gmail.com","subject":"Re: [PATCH v2] doc: `--date` in `git-commit` accepts approxidates","fromName":"Utku","fromEmail":"ugultopu@gmail.com","sentAt":"2021-02-23T19:16:57Z","receivedAt":"2021-02-23T19:18:18Z","isPatch":true,"sender":{"key":"ugultopu@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9937444?v=4"},"body":"I thought it is good to refer the reader to _somewhere_ for\ncompleteness, since those two examples do not cover all cases. Since\nthere is no documentation for it, I referred the reader to the code.\n"},{"id":"417587","messageId":"xmqqtuq21swj.fsf@gitster.g","threadId":"55194","inReplyTo":"YDVFaTGnPCfuJQSa@coredump.intra.peff.net","subject":"Re: [PATCH] doc: `--date` in `git-commit` accepts approxidates","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-02-23T19:33:00Z","receivedAt":"2021-02-23T19:33:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> And then at the end of that section, expand what it's willing to take:\n>\n> ifdef::git-commit[]\n> The `--date` option (but not the environment variables) will also try to\n> make sense of other more human-centric date formats, including relative\n> dates like \"yesterday\" or \"last Friday at noon\".\n> endif::git-commit[]\n\nYup, I find this a lot more acceptable than reference to the code\nthat may happen to be correct only at this moment but can deviate\nover time from the reality. IIRC, the implementation detail cited\nin the patch under review (e.g. use of _careful() helper) did change\nin 2014.\n\nThanks, both. Looking forward to seeing an updated patch.\n"},{"id":"417589","messageId":"xmqqpn0q1stv.fsf@gitster.g","threadId":"55194","inReplyTo":"YDVSICgBwPLtDNu4@coredump.intra.peff.net","subject":"Re: [PATCH v2] doc: `--date` in `git-commit` accepts approxidates","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-02-23T19:34:36Z","receivedAt":"2021-02-23T19:35:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Tue, Feb 23, 2021 at 06:52:02PM +0000, Utku Gultopu via GitGitGadget wrote:\n>\n>> +ifdef::git-commit[]\n>> +In addition to recognizing all date formats above, the `--date` option\n>> +will also try to make sense of other, more human-centric date formats,\n>> +such as relative dates like \"yesterday\" or \"last Friday at noon\". For\n>> +further details on what kind of formats are accepted, please refer to\n>> +the `approxidate_careful` function in `date.c` file in Git source code.\n>> +endif::git-commit[]\n>\n> OK. This is still referring to `approxidate_careful`, which may not be\n> meaningful to most users. But at least it makes a best effort at a\n> hand-waving definition before then. :)\n>\n> I'd probably omit the final sentence entirely (as it may simply confuse\n> people who don't know how to find Git's source), but I'm OK with it\n> either way.\n\nI am not happy with reference to approxidate_careful that has no\nplace in end-user facing documentation. I think the one you\nsuggested struck a better balance.\n"},{"id":"417617","messageId":"E2F9E8D8-0862-433D-BD20-BA3139BEC0C3@gmail.com","threadId":"55194","inReplyTo":"xmqqpn0q1stv.fsf@gitster.g","subject":"Re: [PATCH v2] doc: `--date` in `git-commit` accepts approxidates","fromName":"Utku","fromEmail":"ugultopu@gmail.com","sentAt":"2021-02-23T20:24:58Z","receivedAt":"2021-02-23T20:25:48Z","isPatch":true,"sender":{"key":"ugultopu@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9937444?v=4"},"body":"In this case, maybe Jeff can submit a patch, since I wouldn't be adding\nanything to what he suggested.\n"},{"id":"417619","messageId":"YDVqsnLOGUxX3v42@coredump.intra.peff.net","threadId":"55194","inReplyTo":"E2F9E8D8-0862-433D-BD20-BA3139BEC0C3@gmail.com","subject":"Re: [PATCH v2] doc: `--date` in `git-commit` accepts approxidates","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-02-23T20:50:58Z","receivedAt":"2021-02-23T20:52:15Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Feb 23, 2021 at 03:24:58PM -0500, Utku wrote:\n\n> In this case, maybe Jeff can submit a patch, since I wouldn't be adding\n> anything to what he suggested.\n\nI'm happy to do that to move things along, though really 99% of the work\nwas in your initially identifying the problem. Here's what I would\nsuggest (I did steal your hunk to push all of the --date bits down into\nthat separate paragraph):\n\n-- >8 --\nSubject: [PATCH] doc: mention approxidates for git-commit --date\n\nWe describe the more strict date formats accepted by GIT_COMMITTER_DATE,\netc, but the --date option also allows the looser approxidate formats,\nas well. Unfortunately we don't have a good or complete reference for\nthis format, but let's at least mention that it _is_ looser, and give a\nfew examples.\n\nIf we ever write separate, more complete date-format documentation, we\nshould refer to it from here.\n\nBased-on-a-patch-by: Utku Gultopu \nSigned-off-by: Jeff King \n---\n Documentation/date-formats.txt | 11 +++++++----\n 1 file changed, 7 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt\nindex f1097fac69..99c455f51c 100644\n--- a/Documentation/date-formats.txt\n+++ b/Documentation/date-formats.txt\n@@ -1,10 +1,7 @@\n DATE FORMATS\n ------------\n \n-The `GIT_AUTHOR_DATE`, `GIT_COMMITTER_DATE` environment variables\n-ifdef::git-commit[]\n-and the `--date` option\n-endif::git-commit[]\n+The `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` environment variables\n support the following date formats:\n \n Git internal format::\n@@ -26,3 +23,9 @@ ISO 8601::\n +\n NOTE: In addition, the date part is accepted in the following formats:\n `YYYY.MM.DD`, `MM/DD/YYYY` and `DD.MM.YYYY`.\n+\n+ifdef::git-commit[]\n+In addition to recognizing all date formats above, the `--date` option\n+will also try to make sense of other, more human-centric date formats,\n+such as relative dates like \"yesterday\" or \"last Friday at noon\".\n+endif::git-commit[]\n-- \n2.30.1.1095.g03347429ea\n\n"}]}