So in gitit, we want to be able to get an arbitrary section of a file or
repository's revision history. (The function providing this is used in every
history-related page and bit of functionality, so it's fairly important.)

That is, our Recent Changes page may display 1 year's worth of changes, or maybe
1 day and 1 minute's worth. With Git, we can just pass it a datetime like Thu
Dec 18 18:09:38 UTC 2008, and it'll give us all revisions after that date. Even
if there was no revision at 6:09 that day, but one at 6:10, that 6:10 revision
will be included in the output.

Darcs however, can't seem to do similar stuff. The --match functionality is very
picky and hard to understand, but what I've gathered so far is this:

If I want to use --from-match='date foo', then any precise date like the one
given above *must* be the date of a patch. If it isn't, if it's off at all, then
Darcs errors out.
If I want to use the strange human-readable dates, then I can go
'--from-match=date since 2008-12', or '--from-match=date since 2008-12-18', but
I simply can't get any more precise than that. There are no examples including
minutes and seconds, and all the variants I've tried end with that irksome error
message about 'fancy dates'.

So I am left with no simple approach. There are a number of workarounds, each
more hideous than the last (round to month so I can use --from-match date since
year-month; get the entire history and do XML parsing to make up for darcs' lack
of intelligence in --from-match etc.). 

But much much better would be to change darcs such that: if --from/to-match are
passed a specific date, they return every patch after/before that date,
including any patch on that date (if it exists, and *not* erroring out if it
doesn't!).

On Sat, Jan 17, 2009 at 18:18:25 -0000, gwern wrote:
> If I want to use the strange human-readable dates, then I can go
> '--from-match=date since 2008-12', or '--from-match=date since 2008-12-18', but
> I simply can't get any more precise than that. There are no examples including
> minutes and seconds, and all the variants I've tried end with that irksome error
> message about 'fancy dates'.

Does 'after' work better for you than 'since'?

Also, I've trained myself lately to use quotation marks, e.g.
--match='date "after 2008-12"'

'Since' does not appear to be supported by the English date parser (it's
likely that the documentation is misleading on that; sorry).  It sounds
like this may just be a request to provide better documentation for the
English dates.

No, 'after' works just as poorly as 'since':

gwern@craft:36883~/darcs-news>darcs changes --from-match='date "after Thu Dec 18
18:09:38 UTC 2008"'
darcs: Can't support fancy dates.

For further reference, this is the error when using a precise date:

gwern@craft:36884~/darcs-news>darcs changes --from-match='date "Thu Dec 18
18:09:38 UTC 2008"'
darcs: Couldn't find patch matching "date "Thu Dec 18 18:09:38 UTC 2008""

On Sat, Jan 17, 2009 at 18:57:43 -0000, gwern wrote:
> No, 'after' works just as poorly as 'since':
> 
> gwern@craft:36883~/darcs-news>darcs changes --from-match='date "after Thu Dec 18
> 18:09:38 UTC 2008"'
> darcs: Can't support fancy dates.

The English date parser only accepts ISO 8601 dates, I think.
So you can do things like "after 2008-12-18 18:09:38+0000"
but not the above.

> The English date parser only accepts ISO 8601 dates, I think.
> So you can do things like "after 2008-12-18 18:09:38+0000"
> but not the above.

I see. So perhaps this is a documentation bug after all - the docs need to
mention that the dates are that particular ISO format (which isn't deducible
from the examples) and that someone wanting more precision needs to use the full
format instead.

In issue1323, Eric wrote:
> The English date parser only accepts ISO 8601 dates, I think.  So
> you can do things like "after 2008-12-18 18:09:38+0000" but not the
> above.

ISO 8601 defines a hell of a lot more than the basic date/time format
%Y-%m-%dT%H:%m:%S%z.  Instead of ISO 8601, we should probably refer to
RFC 3339.  GNU date(1) has already done so.

>From Wikipedia:

  RFC 3339 defines a profile of ISO 8601 for the use in Internet
  protocols and standards. It explicitly excludes durations and dates
  before the common era. The more complex formats like week numbers
  and ordinal day are not permitted.

http://tools.ietf.org/html/rfc3339

Trent W. Buck wrote:
> ISO 8601 defines a hell of a lot more than the basic date/time format
> %Y-%m-%dT%H:%m:%S%z.  Instead of ISO 8601, we should probably refer to
> RFC 3339.  GNU date(1) has already done so.

I'm unassigning this task from me, because IsoDate.hs (and OldDate.hs)
do appear to implement more than RFC 3339 alone.  For example, RFC
3339 doesn't mention time intervals at all, but IsoDate has
"iso8601_interval" and "english_interval".

I'm reluctant to take responsibility for this issue; I can't even
afford a copy of ISO 8601 (unlike RFCs, ISO specs aren't gratis).

I do note that the haddock coverage of IsoDate appears pretty solid,
so perhaps user documentation should simply say "we implement SOME of
ISO 8601", give copious examples, and then refer users to the Haddock
documentation.  This is more-or-less what's done currently.