{"thread":{"id":"55406","subject":"[PATCH] Documentation: updated documentation for git commit --date","startedAt":"2021-03-28T10:20:29Z","lastAt":"2021-03-30T17:28:49Z","messageCount":9,"participants":["Chinmoy via GitGitGadget","Bagas Sanjaya","Chinmoy Chakraborty","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"420378","messageId":"pull.918.git.1616926790227.gitgitgadget@gmail.com","threadId":"55406","inReplyTo":null,"subject":"[PATCH] Documentation: updated documentation for git commit --date","fromName":"Chinmoy via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2021-03-28T10:19:49Z","receivedAt":"2021-03-28T10:20:29Z","isPatch":true,"sender":{"key":"name:Chinmoy","avatar":null},"body":"From: Chinmoy Chakraborty \n\nThis commit lists the special strings used with `--date`\nin `git-commit.txt` and also a brief explanation about\nthe strings in `date-formats.txt`.\n\nSigned-off-by: Chinmoy Chakraborty \n---\n Documentation: updated documentation for git commit --date\n \n This commit lists the special strings used with --date in git-commit.txt\n and also a brief explanation about the strings in date-formats.txt.\n \n Signed-off-by: Chinmoy Chakraborty chinmoy12c@gmail.com\n \n \n Related Issue\n =============\n \n #302\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-918%2Fchinmoy12c%2Fissue_302-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-918/chinmoy12c/issue_302-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/918\n\n Documentation/date-formats.txt | 32 ++++++++++++++++++++++++++++++++\n Documentation/git-commit.txt | 5 ++++-\n 2 files changed, 36 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt\nindex 99c455f51c04..66dae179eb66 100644\n--- a/Documentation/date-formats.txt\n+++ b/Documentation/date-formats.txt\n@@ -1,6 +1,38 @@\n+[[DATE FORMATS]]\n DATE FORMATS\n ------------\n \n+`yesterday`::\n+\tChange commit time to yesterday, that is, 24 hours ago.\n+\n+`noon`::\n+\tChange commit time to noon, that is 12:00. If current\n+\ttime is less than 12:00, the time will be set to 12:00\n+\ton the previous day, else it will be set to 12:00 on\n+\tthe same day.\n+\n+`midnight`::\n+\tChange commit time to midnight, that is, 00:00.\n+\n+`tea`::\n+\tChange commit time to 17:00(tea time). If the current\n+\ttime is less than 17:00, the time will be set to 17:00\n+\ton the previous day, else it will be set to 17:00 on\n+\tthe same day.\n+\n+`PM`::\n+\tChange commit time from AM to PM. If the current time\n+\tis already greater than 12:00, then the time remains\n+\tunaltered.\n+\n+`AM`::\n+\tChange commit time from PM to AM. If current time is\n+\talready less than 12:00, then the time remains\n+\tunaltered.\n+\n+`now`::\n+\tChange commit time to current time.\n+\n The `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` environment variables\n support the following date formats:\n \ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 3c69f461c9af..b2f51cdcafaf 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -176,7 +176,10 @@ See linkgit:git-rebase[1] for details.\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 value of \n+\tmay be any one of the following special values - \"yesterday\",\n+\t\"noon\", \"midnight\", \"tea\", \"PM\", \"AM\", \"never\", \"now\"\n+\t(see <>).\n \n -m ::\n --message=::\n\nbase-commit: 84d06cdc06389ae7c462434cb7b1db0980f63860\n-- \ngitgitgadget\n"},{"id":"420387","messageId":"pull.918.v2.git.1616936099778.gitgitgadget@gmail.com","threadId":"55406","inReplyTo":"pull.918.git.1616926790227.gitgitgadget@gmail.com","subject":"[PATCH v2] Documentation: updated documentation for git commit --date","fromName":"Chinmoy via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2021-03-28T12:54:59Z","receivedAt":"2021-03-28T12:56:00Z","isPatch":true,"sender":{"key":"name:Chinmoy","avatar":null},"body":"From: Chinmoy Chakraborty \n\nThis commit lists the special strings used with `--date`\nin `git-commit.txt` and also a brief explanation about\nthe strings in `date-formats.txt`.\n\nSigned-off-by: Chinmoy Chakraborty \n---\n Documentation: updated documentation for git commit --date\n \n This commit lists the special strings used with --date in git-commit.txt\n and also a brief explanation about the strings in date-formats.txt.\n \n Signed-off-by: Chinmoy Chakraborty chinmoy12c@gmail.com\n \n \n Related Issue\n =============\n \n #302\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-918%2Fchinmoy12c%2Fissue_302-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-918/chinmoy12c/issue_302-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/918\n\nRange-diff vs v1:\n\n 1: 818ac39b5203 ! 1: 20da93dea971 Documentation: updated documentation for git commit --date\n @@ Commit message\n \n ## Documentation/date-formats.txt ##\n @@\n -+[[DATE FORMATS]]\n ++[[DATE-FORMATS]]\n DATE FORMATS\n ------------\n \n @@ Documentation/git-commit.txt: See linkgit:git-rebase[1] for details.\n +\tOverride the author date used in the commit. The value of \n +\tmay be any one of the following special values - \"yesterday\",\n +\t\"noon\", \"midnight\", \"tea\", \"PM\", \"AM\", \"never\", \"now\"\n -+\t(see <>).\n ++\t(see <>).\n \n -m ::\n --message=::\n\n\n Documentation/date-formats.txt | 32 ++++++++++++++++++++++++++++++++\n Documentation/git-commit.txt | 5 ++++-\n 2 files changed, 36 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt\nindex 99c455f51c04..83c423a3ec2e 100644\n--- a/Documentation/date-formats.txt\n+++ b/Documentation/date-formats.txt\n@@ -1,6 +1,38 @@\n+[[DATE-FORMATS]]\n DATE FORMATS\n ------------\n \n+`yesterday`::\n+\tChange commit time to yesterday, that is, 24 hours ago.\n+\n+`noon`::\n+\tChange commit time to noon, that is 12:00. If current\n+\ttime is less than 12:00, the time will be set to 12:00\n+\ton the previous day, else it will be set to 12:00 on\n+\tthe same day.\n+\n+`midnight`::\n+\tChange commit time to midnight, that is, 00:00.\n+\n+`tea`::\n+\tChange commit time to 17:00(tea time). If the current\n+\ttime is less than 17:00, the time will be set to 17:00\n+\ton the previous day, else it will be set to 17:00 on\n+\tthe same day.\n+\n+`PM`::\n+\tChange commit time from AM to PM. If the current time\n+\tis already greater than 12:00, then the time remains\n+\tunaltered.\n+\n+`AM`::\n+\tChange commit time from PM to AM. If current time is\n+\talready less than 12:00, then the time remains\n+\tunaltered.\n+\n+`now`::\n+\tChange commit time to current time.\n+\n The `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` environment variables\n support the following date formats:\n \ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 3c69f461c9af..1935fad33f35 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -176,7 +176,10 @@ See linkgit:git-rebase[1] for details.\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 value of \n+\tmay be any one of the following special values - \"yesterday\",\n+\t\"noon\", \"midnight\", \"tea\", \"PM\", \"AM\", \"never\", \"now\"\n+\t(see <>).\n \n -m ::\n --message=::\n\nbase-commit: 84d06cdc06389ae7c462434cb7b1db0980f63860\n-- \ngitgitgadget\n"},{"id":"420431","messageId":"6a9d24a9-6942-97fc-550f-6b9b61264a78@gmail.com","threadId":"55406","inReplyTo":"pull.918.v2.git.1616936099778.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] Documentation: updated documentation for git commit --date","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-03-29T05:25:31Z","receivedAt":"2021-03-29T05:33:43Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 28/03/21 19.54, Chinmoy via GitGitGadget wrote:\n> From: Chinmoy Chakraborty \n> \n> This commit lists the special strings used with `--date`\n> in `git-commit.txt` and also a brief explanation about\n> the strings in `date-formats.txt`.\n> \n> Signed-off-by: Chinmoy Chakraborty \n> ---\nIs date format parsing specific to git commit? If so, then\nwhy not date-formats.txt be merged to `DATE FORMATS` section\nof git-commit documentation? Also, what commit this `--date`\noption first appeared before you write this documentation?\n\n> +`tea`::\n> +\tChange commit time to 17:00(tea time). If the current\n> +\ttime is less than 17:00, the time will be set to 17:00\n> +\ton the previous day, else it will be set to 17:00 on\n> +\tthe same day.\nHow useful is this argument?\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"420433","messageId":"98c196c4-31ff-4df1-9215-77d115771583@gmail.com","threadId":"55406","inReplyTo":"6a9d24a9-6942-97fc-550f-6b9b61264a78@gmail.com","subject":"Re: [PATCH v2] Documentation: updated documentation for git commit --date","fromName":"Chinmoy Chakraborty","fromEmail":"chinmoy12c@gmail.com","sentAt":"2021-03-29T06:02:38Z","receivedAt":"2021-03-29T06:01:59Z","isPatch":true,"sender":{"key":"chinmoy12c@gmail.com","avatar":"https://avatars.githubusercontent.com/u/57670338?v=4"},"body":"\nOn 3/29/21 10:55 AM, Bagas Sanjaya wrote:\n> Is date format parsing specific to git commit? If so, then\n> why not date-formats.txt be merged to `DATE FORMATS` section\n> of git-commit documentation?\nIt is already included below the `COMMIT INFORMATION` section.\n\n> Also, what commit this `--date`\n> option first appeared before you write this documentation?\n\nI guess it was introduced in commit \na8aca418d6484400d6804e22717bd49ca06c28e9.\n\n>\n>> +`tea`::\n>> +    Change commit time to 17:00(tea time). If the current\n>> +    time is less than 17:00, the time will be set to 17:00\n>> +    on the previous day, else it will be set to 17:00 on\n>> +    the same day.\n> How useful is this argument?\n>\nI think initially it was suggested as a joke, but actually implemented\n\nto demonstrate the ability for users to include their own custom\n\ntime/date periods.\n\nSee : \nhttps://github.com/git/git/commit/a8aca418d6484400d6804e22717bd49ca06c28e9\n\n"},{"id":"420448","messageId":"5f69547a-723c-05d4-e00c-c7a5d6760315@gmail.com","threadId":"55406","inReplyTo":"98c196c4-31ff-4df1-9215-77d115771583@gmail.com","subject":"Re: [PATCH v2] Documentation: updated documentation for git commit --date","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-03-29T11:11:25Z","receivedAt":"2021-03-29T11:12:07Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 29/03/21 13.02, Chinmoy Chakraborty wrote:\n\n> I think initially it was suggested as a joke, but actually implemented\n> \n> to demonstrate the ability for users to include their own custom\n> \n> time/date periods.\n> \nHmmm...\n\nThe commit you mentioned (a8aca418d6484400d6804e22717bd49ca06c28e9)\nsaid that:\n\n> Thanks for pointing out tea-time.\n> \n> This is also written to easily extended to allow people to add their own\n> important dates like Christmas and their own birthdays.\n> \n\nBut it seems like the predefined dates/times were hard-coded, so to extend\n--date option to allow more predefined date/times, Git sources need to\nbe edited.\n\nMaybe we can make git config option (commit.predefined_times [FIXME: suggest\nbetter name]) so user can easily add ones.\n\nAlso, I asked to you: can I set --date to arbitrary date (like 09/29/2009\n19:59)?\n\n[CC] Junio, what about this patch?\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"420480","messageId":"25198354-9d0a-4ba9-f0a0-13301432b3fa@gmail.com","threadId":"55406","inReplyTo":"5f69547a-723c-05d4-e00c-c7a5d6760315@gmail.com","subject":"Re: [PATCH v2] Documentation: updated documentation for git commit --date","fromName":"Chinmoy Chakraborty","fromEmail":"chinmoy12c@gmail.com","sentAt":"2021-03-29T14:56:38Z","receivedAt":"2021-03-29T14:56:15Z","isPatch":true,"sender":{"key":"chinmoy12c@gmail.com","avatar":"https://avatars.githubusercontent.com/u/57670338?v=4"},"body":"\nOn 3/29/21 4:41 PM, Bagas Sanjaya wrote:\n>\n> Also, I asked to you: can I set --date to arbitrary date (like 09/29/2009\n> 19:59)?\n\n\nSure you can use something like git commit --date='2009-09-29 19:59:00'\n\nor git commit --date=`2 days ago`\n\n"},{"id":"420518","messageId":"xmqqim59irba.fsf@gitster.g","threadId":"55406","inReplyTo":"pull.918.v2.git.1616936099778.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] Documentation: updated documentation for git commit --date","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-03-29T21:27:21Z","receivedAt":"2021-03-29T21:28:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Chinmoy via GitGitGadget\" writes:\n\n> From: Chinmoy Chakraborty \n>\n> This commit lists the special strings used with `--date`\n> in `git-commit.txt` and also a brief explanation about\n> the strings in `date-formats.txt`.\n\nAll of that can be read from the patch text. What an author is\nexpected to explain in the proposed commit log message is WHY.\n\nWhy is it a good idea to list possible arguments --date can take?\n\nThe reason can include \"because so far they are not explained\nanywhere.\"\n\nDocumentation/SubmittingPatches::describe-changes, especially\n[[meaningful-message]], is a good source to learn what a title and a\nproposed log message of a patch should look like in this project.\n\n> diff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt\n> index 99c455f51c04..83c423a3ec2e 100644\n> --- a/Documentation/date-formats.txt\n> +++ b/Documentation/date-formats.txt\n> @@ -1,6 +1,38 @@\n> +[[DATE-FORMATS]]\n> DATE FORMATS\n> ------------\n> \n> +`yesterday`::\n> +\tChange commit time to yesterday, that is, 24 hours ago.\n> +\n> +`noon`::\n> +\tChange commit time to noon, that is 12:00. If current\n> +\ttime is less than 12:00, the time will be set to 12:00\n> +\ton the previous day, else it will be set to 12:00 on\n> +\tthe same day.\n> +\n> +`midnight`::\n> +\tChange commit time to midnight, that is, 00:00.\n> +\n> +`tea`::\n> +\tChange commit time to 17:00(tea time). If the current\n> +\ttime is less than 17:00, the time will be set to 17:00\n> +\ton the previous day, else it will be set to 17:00 on\n> +\tthe same day.\n> +\n> +`PM`::\n> +\tChange commit time from AM to PM. If the current time\n> +\tis already greater than 12:00, then the time remains\n> +\tunaltered.\n> +\n> +`AM`::\n> +\tChange commit time from PM to AM. If current time is\n> +\talready less than 12:00, then the time remains\n> +\tunaltered.\n> +\n> +`now`::\n> +\tChange commit time to current time.\n\nThe \"commit\" related documentation is not the only consumer of this\nfile. These new descriptions repeatedly stress \"commit time\", but\nare these acceptable to readers of other page(s) that include this\nfile, or is the discrepancy irritating to them?\n\nIn any case, I personally think these should NOT be described at the\nbeginning of this file. The primary formats the end-users should\nlearn to use are the ones that are described already in the\ndocument. All of the above are more like \"by the way, did you know\nthat 'git-commit --date' takes these cute strings? easter eggs.\n\nI am not very strongly opposed to extending the tail end of the\nexisting contents of the file, namely:\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\nand explain what \"such as ...\" is, but I am fairly negative on\nteaching 'tea' to our users before we talk about 2822 and 8601\nformats. I actually think the above three lines strikes a good\nbalance---we do not want the users to be surprised too much when\nthey see \"--date yesterday\" to work, but we do not particularly\nwant to encourage them to use \"commit --date noon\" [*1*].\n\n> The `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` environment variables\n> support the following date formats:\n> \n> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\n> index 3c69f461c9af..1935fad33f35 100644\n> --- a/Documentation/git-commit.txt\n> +++ b/Documentation/git-commit.txt\n> @@ -176,7 +176,10 @@ See linkgit:git-rebase[1] for details.\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 value of \n> +\tmay be any one of the following special values - \"yesterday\",\n> +\t\"noon\", \"midnight\", \"tea\", \"PM\", \"AM\", \"never\", \"now\"\n> +\t(see <>).\n\nLikewise. I am OK with adding (see date-formats) but against\nlisting the easter eggs as if they are more important than other\nforms.\n\nThanks.\n\n\n[Footnote]\n\n*1* The approxidate is useful when a rough \"around that time\"\n specification suffices, e.g. \"git log --since='last.week'\". The\n user is OK to see commits down to roughly a week old, and would\n not be upset if a commit with a timestamp that is 9 days old\n shown.\n\n On the other hand, it would be unusual that somebody cares\n enough to use \"git commit --date\" but yet it is OK that the time\n recorded is fuzzy. For that reason alone, I am in general\n negative on the direction this patch tries to take us in.\n\n\n\n"},{"id":"420627","messageId":"f0200d12-2c0f-ee36-551f-f8133a4dea20@gmail.com","threadId":"55406","inReplyTo":"xmqqim59irba.fsf@gitster.g","subject":"Re: [PATCH v2] Documentation: updated documentation for git commit --date","fromName":"Chinmoy Chakraborty","fromEmail":"chinmoy12c@gmail.com","sentAt":"2021-03-30T16:38:08Z","receivedAt":"2021-03-30T16:37:31Z","isPatch":true,"sender":{"key":"chinmoy12c@gmail.com","avatar":"https://avatars.githubusercontent.com/u/57670338?v=4"},"body":"\nOn 3/30/21 2:57 AM, Junio C Hamano wrote:\n> All of that can be read from the patch text. What an author is\n> expected to explain in the proposed commit log message is WHY.\n>\n> Why is it a good idea to list possible arguments --date can take?\n>\n> The reason can include \"because so far they are not explained\n> anywhere.\"\n>\n> Documentation/SubmittingPatches::describe-changes, especially\n> [[meaningful-message]], is a good source to learn what a title and a\n> proposed log message of a patch should look like in this project.\n\nOkay I'll update the patch with proper commit message.\n\n\n> I am not very strongly opposed to extending the tail end of the\n> existing contents of the file, namely:\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>\n> and explain what \"such as ...\" is, but I am fairly negative on\n> teaching 'tea' to our users before we talk about 2822 and 8601\n> formats. I actually think the above three lines strikes a good\n> balance---we do not want the users to be surprised too much when\n> they see \"--date yesterday\" to work, but we do not particularly\n> want to encourage them to use \"commit --date noon\" [*1*].\n\nOkay so I guess it's better to just extend the tail of the file\n\nto explain a little bit about the relative dates and leave\n\nout the Easter eggs and formats like 'noon' and 'midnight'\n\n\n> Likewise. I am OK with adding (see date-formats) but against\n> listing the easter eggs as if they are more important than other\n> forms.\n\nOkay I'll just add the (see date-formats) and leave out the\n\nexhaustive list.\n\n\n>\n> [Footnote]\n>\n> *1* The approxidate is useful when a rough \"around that time\"\n> specification suffices, e.g. \"git log --since='last.week'\". The\n> user is OK to see commits down to roughly a week old, and would\n> not be upset if a commit with a timestamp that is 9 days old\n> shown.\n>\n> On the other hand, it would be unusual that somebody cares\n> enough to use \"git commit --date\" but yet it is OK that the time\n> recorded is fuzzy. For that reason alone, I am in general\n> negative on the direction this patch tries to take us in.\n\nSo according to you, is it a relevant/worthwhile change\n\nto add in docs?\n\n\nThanks.\n\n"},{"id":"420631","messageId":"xmqqsg4ceel4.fsf@gitster.g","threadId":"55406","inReplyTo":"f0200d12-2c0f-ee36-551f-f8133a4dea20@gmail.com","subject":"Re: [PATCH v2] Documentation: updated documentation for git commit --date","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-03-30T17:28:07Z","receivedAt":"2021-03-30T17:28:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Chinmoy Chakraborty writes:\n\n>> [Footnote]\n>>\n>> *1* The approxidate is useful when a rough \"around that time\"\n>> specification suffices, e.g. \"git log --since='last.week'\". The\n>> user is OK to see commits down to roughly a week old, and would\n>> not be upset if a commit with a timestamp that is 9 days old\n>> shown.\n>>\n>> On the other hand, it would be unusual that somebody cares\n>> enough to use \"git commit --date\" but yet it is OK that the time\n>> recorded is fuzzy. For that reason alone, I am in general\n>> negative on the direction this patch tries to take us in.\n>\n> So according to you, is it a relevant/worthwhile change\n>\n> to add in docs?\n\nThat depends on the \"docs\".\n\nIf we do not hint that relative dates are also usable, in addition\nto the more common date formats like RFC2822 and ISO8601, for \"log\n--since\" and other options that are used to specify a boundary for\nlooking up existing things, extending their documentation may be\nworth doing.\n\nGiving 'tea' and other oddities at the top as if they are more\nimportant than the formats that is used to give more precise input\nfor options that are used to specify what timestamp is recorded in\nan object the command is about to create would be a change with\nnegative value.\n\nThanks.\n"}]}