From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 06 Jul 2017 18:03:35 GMT
Subject: Re: bug report: dates on diff
Message-ID: <xmqqbmoxfnns.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <53f97d43-6984-6a46-bde2-a8cf64e7bb9e@email.unc.edu>

Todd Lewis <utoddl@email.unc.edu> writes:

> Trying not to sound snide, but, what's the point of "--date=" on commits if you
> can't use it later? Granted, things always seem harder until you understand how
> the work. Thanks again.

You do not sound snide at all, at least to me ;-)

Imagine this scenario:

 - Contributor A writes a change on 2017-07-01 and send it in to me
 - Contributor B writes a change on 2017-07-03 and send it in to me
 - I apply change from B on 2017-07-04 on 'master'
 - I apply change from A on 2017-07-05 on 'master'
 - You clone the resulting repository from me on 2017-07-06

Now, you have at the tip of 'master' in your repository the commit
that records the change by contributor A.

And there are three times that are relevant to your tip of 'master'.

 - When was the commit that sits at the tip of 'master' made?
 - When was the change recorded in that commit made?
 - When was the commit made at the tip of _your_ 'master'?

and the answers are 2017-07-01, 2017-07-05 and 2017-07-06, respectively.
They are called "committer", "author" and "reflog" timestamps.

The 'master@{<time>}' syntax is about the reflog timestamp.  It
never looks at the former two.  In general whenever you see <ref>@{...},
that is talking about the information that is stored in "reflog",
the record of when and in what order the <ref> in _your_ repository
pointed at various objects.

The "commit --date=<time>" is about tweaking the "author" timestamp
the commit records.  It does not affect the "committer" timestamp.
By definition (of what "reflog" is), it will not affect the reflog
timestamp, because the reflog timestamp for a particular commit
would be different across repositories.  I had A's commit on _my_
master on 2017-07-05, but the time you had it on _your_ master was
not until 2017-07-06.

I think the best way to do this properly would be to extend the
"<ref>^{...}" syntax so that we can say e.g.

    git show "master^{#author-time > 2017-01-01}"

to mean "traverse from the tip of 'master' and find the first commit
that satisfies the given expression, "author-time > 2017-01-01", i.e.
has author timestamp that is later than the specified date.  Which
would be in line with the existing

    git show "master^{/my commit message}"

that means "traverse from the tip of 'master' and find the first
commit that has 'my commit message' in the log message".

Note that "git log --since=<time> --until=<time> master" would be
the thing that is closest to what you would want that already
exists, but that limits by the "committer" timestamp.  You _could_
lie about both author and committer timestamp when building the
backdated history and use this mechanism, but we have author and
committer timestamps that are distinct for a reason, so it is a
rather poor workaround.