git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Junio C Hamano <gitster@pobox.com>
To: Danh Doan <congdanhqx@gmail.com>
Cc: Dmitry Kulikov <dima@koulikoff.ru>, git@vger.kernel.org
Subject: Re: git log --since=<date>
Date: Sat, 02 May 2020 09:21:44 -0700	[thread overview]
Message-ID: <xmqqzhaqjoiv.fsf@gitster.c.googlers.com> (raw)
In-Reply-To: <20200502110350.GA3143@danh.dev> (Danh Doan's message of "Sat, 2 May 2020 18:03:50 +0700")

Danh Doan <congdanhqx@gmail.com> writes:

> On 2020-05-02 07:54:03+0200, Dmitry Kulikov <dima@koulikoff.ru> wrote:
>> On Friday 01 May 2020 15:03:10 Junio C Hamano wrote:
>> > You of course can say "git log --since=yesterday.midnight" if you
>> > want to be exact ;-).
>> 
>>   What should I enter instead --since=2020-05-01 to have a midnight time?
>
>
> You can use the same syntax:
>
> 	git log --since='2020-05-01 midnight'
> 	# or ISO-8601
> 	git log --since='2020-05-01 00:00:00'

Perhaps the use of <date> in the documentation is what is causing
this confusion?  Would <timestamp> or <datetime> work better?

There is Documentation/date-formats.txt that is included by the help
pages for "git commit-tree", "git commit" and "git tag".  These pages
consistently use "date" and does not say timestamp nor datetime, so
the noun we use in "git log" documentation is OK.

But the date-formats documentation is not included there, so we
would be OK once we

 (1) adjust the contents of the date-formats.txt documentation to
     make sure it can be used in "git log" documentation, and

 (2) find the right place to include it in "git log" documentation.

Here is a rough draft to do so.  I was tempted not to touch
git-log.txt and instead include it in rev-list-options.txt (where
"--since" and friends are described), but the structure of the
document was not ready for that.  If somebody wants to go in that
direction, it might be better as it would allow us to cover things
like "git shortlog --since=3.months.ago", but then we probably
should do the following before we can do so:

 (1) remove the section title and its header level from
     date-formats.txt, and adjust the existing pages that include
     it, and

 (2) find the right place in rev-list-options.txt, and

 (3) make sure everybody that includes rev-list-options.txt are
     happy with the added description (if some of them do not offer
     an option to specify ranges, they must conditionally be
     excluded from using date-formats.txt).

Thanks.

 Documentation/date-formats.txt | 25 ++++++++++++++++++-------
 Documentation/git-commit.txt   |  1 -
 Documentation/git-log.txt      |  2 ++
 3 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt
index 6926e0a4c8..ce6f6bdb95 100644
--- a/Documentation/date-formats.txt
+++ b/Documentation/date-formats.txt
@@ -1,11 +1,10 @@
-DATE FORMATS
-------------
+DATE INPUT FORMATS
+------------------
 
-The `GIT_AUTHOR_DATE`, `GIT_COMMITTER_DATE` environment variables
-ifdef::git-commit[]
-and the `--date` option
-endif::git-commit[]
-support the following date formats:
+The `GIT_AUTHOR_DATE`, `GIT_COMMITTER_DATE` environment variables,
+the `--date` option of `git commit`, and
+the options like `--since` of `git log`,
+all of which specify date-time, support the following date formats:
 
 Git internal format::
 	It is `<unix timestamp> <time zone offset>`, where `<unix
@@ -24,3 +23,15 @@ ISO 8601::
 +
 NOTE: In addition, the date part is accepted in the following formats:
 `YYYY.MM.DD`, `MM/DD/YYYY` and `DD.MM.YYYY`.
++
+NOTE: Some human-friendly date and time (e.g. `yesterday`,
+`midnight`, `4 days ago`) are also accepted.  
+The full list is left as trivia for readers to discover.
++
+NOTE: A date-time that lacks time-part is taken to be the same time on
+that day.  For example, `yesterday` used at 8 in the morning means 8 in the
+morning yesterday.  A date-time that lacks date-part is taken to be
+the given time on the same day (if the time has already passed) or
+on the day before (otherwise).  For example, `8AM` used at 9 in the morning
+means an hour ago the same day, while `noon` used at 9 in the morning 
+is taken as the noon the day before.
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index a3baea32ae..70cf5d9d4f 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -494,7 +494,6 @@ the environment variables.
 The typical usage is to set just the `user.name` and `user.email` variables;
 the other options are provided for more complex use cases.
 
-:git-commit: 1
 include::date-formats.txt[]
 
 DISCUSSION
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 20e6d21a74..d2bda18d45 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -109,6 +109,8 @@ options or the revision range, when confusion arises.
 
 include::rev-list-options.txt[]
 
+include::date-formats.txt[]
+
 include::pretty-formats.txt[]
 
 COMMON DIFF OPTIONS

  parent reply	other threads:[~2020-05-02 16:22 UTC|newest]

Thread overview: 7+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-05-01 21:35 git log --since=<date> Dmitry Kulikov
2020-05-01 22:03 ` Junio C Hamano
2020-05-02  5:54   ` Dmitry Kulikov
2020-05-02 11:03     ` Danh Doan
2020-05-02 11:52       ` Dmitry Kulikov
2020-05-02 16:21       ` Junio C Hamano [this message]
2020-05-02 12:02     ` Dmitry Kulikov

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=xmqqzhaqjoiv.fsf@gitster.c.googlers.com \
    --to=gitster@pobox.com \
    --cc=congdanhqx@gmail.com \
    --cc=dima@koulikoff.ru \
    --cc=git@vger.kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).