Re: ambiguous git-log date and timestamp syntax

From: Linus Torvalds <torvalds@linux-foundation.org>
Date: Mar 1, 2008, 21:46 UTC
Message-ID: <alpine.LFD.1.00.0803011010480.17889@woody.linux-foundation.org>
In-Reply-To: <m3d4qejroy.fsf@localhost.localdomain>

On Sat, 1 Mar 2008, Jakub Narebski wrote:

Show 9 quoted lines

> > 
> > From what I can tell it seems that dates can be specified relatively,
> > e.g. "2 hours ago", or with any ISO 8601 or RFC 2822 date syntax. Is
> > this correct, and are there any docs on specifying relative dates?
> 
> I don't know why git doesn't use getdate_r for this, instead rolling
> out its own date parsing routines: approxidate*, parse_date. From what
> I remember it should accept any date "date" (from coreutils) accepts,
> but it does (from comments) for date to be in "C" locale.

strptime() and getdate() are totally unusable for any real date parsing where you don't already know the exact format(s) of the string. And neither of them can do any of the useful things that approxidate() does, ie handle strings like "two months ago".

So yes, we do our own date parsing, where the "exact" format is the Unix epoch timestamp (potentially together with explicit TZ information), but we try to parse a wide variety of user-supplied strings that match any of the standard formats (and do that loosely, so that when emails etc invariably get things wrong and don't actually follow rfc2822 exactly, for example, it still tries to make sense of it).

And then when the more-or-less exact format check fails, we fall back on the really approximate guessing, which accepts any random input and turns it into a date (ie "two days ago at noon" will give you *some* results, but whether they are the results you meant or not is debatable: I think "noon" will always round down to the previous noon, for example, so it migth be closer to three days ago).

So the "timestamp" is a pure integer (seconds since epoch), and in most other places git will accept dates that are more or less any half-way sane format for interchange.

Of course, the only reason for --max-age=timestamp, --min-age=timestamp existing int he first place is that *historically* normal git commands could only parse the strict "seconds since epoch", and we had that magical special "git rev-parse" function that turned the human-readable date into an exact timestamp.

You can still see it:

	[torvalds@woody git]$ git-rev-parse  --until="2.hours.ago"

outputs

	--min-age=1204387613

which is the machine-readable format, but that's purely historical, since now all commands that take that machine-readable format also take the human format directly, so it might make more sense to just not even document that "--[min|max]-age=timestamp" thing.

			Linus