ambiguous git-log date and timestamp syntax

ambiguous git-log date and timestamp syntax

[Rhodes, Kate]

The docs are a little vague on exactly what your options are when  
specifying dates. If someone can provide me some details on this i'll  
make a patch for the docs.

--since=date, --after=date
	Show commits more recent than a specific date.
--until=date, --before=date
	Show commits older than a specific date.
--max-age=timestamp, --min-age=timestamp
	Limit the commits output to specified time range.

 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 can't find any details on what the "timestamp" format should be. Can  
someone point me in the right direction?

-Kate == masukomi

Re: ambiguous git-log date and timestamp syntax

[Jakub Narebski]

"Rhodes, Kate" <masukomi@gmail.com> writes:

> The docs are a little vague on exactly what your options are when
> specifying dates. If someone can provide me some details on this I'll
> make a patch for the docs.
> 
> --since=date, --after=date
> 	Show commits more recent than a specific date.
> --until=date, --before=date
> 	Show commits older than a specific date.

Those are porcelain (meant for user) options.

> --max-age=timestamp, --min-age=timestamp
> 	Limit the commits output to specified time range.

Those are plumbing (meant for scripts) options.

For example git-rev-parse translates --since into --max-age, etc.

> 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.

So I'm sorry, but I cannot help you here...

> I can't find any details on what the "timestamp" format should be. Can
> someone point me in the right direction?

Timestamp is Unix date (epoch), i.e. number of seconds since
1970-01-01 00:00:00 UTC, the format git uses for dates in commit and
tag objects.
 
> -Kate == masukomi
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: ambiguous git-log date and timestamp syntax

[Linus Torvalds]

On Sat, 1 Mar 2008, Jakub Narebski wrote:
> > 
> > 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

Re: ambiguous git-log date and timestamp syntax

[Jakub Narebski]

On Sat, 1 Mar 2008, Linus Torvalds wrote:
> On Sat, 1 Mar 2008, Jakub Narebski wrote:
> > > 
> > > 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).

I wonder how it compares with GNU date (from GNU Corutils) inexact date
parsing (and why we couldn't lift the code from GNU date)... I guess that
main goal was to parse correctly "mail" dates, first.


BTW. Git has few other such "reimplementing the wheel" things, like strbuf,
or ALLOC_GROW, or it's own parseopt. I guess main reasons are to avoid
adding yet another dependency, and that existing solutions doesn't fill
all git needs.

-- 
Jakub Narebski
Poland

Re: ambiguous git-log date and timestamp syntax

[Johannes Schindelin]

Hi,

On Sat, 1 Mar 2008, Jakub Narebski wrote:

> BTW. Git has few other such "reimplementing the wheel" things, like 
> strbuf, or ALLOC_GROW, or it's own parseopt. I guess main reasons are to 
> avoid adding yet another dependency, and that existing solutions doesn't 
> fill all git needs.

Or that the existing wheels are quadratic wheels, and flat.

Just look at our own parse-options.[ch].  It is _still_ smaller and less 
difficult to read than GNU getopt.  Yet, it is also much more powerful and 
easier to use.

Likewise, strbuf compares to Bstring, for example (although you might say 
that Bstring is more powerful, but it comes at a price: it clutters the 
namespace, and is not as performant as strbuf).

ALLOC_GROW() is so small as to not merit any third-party dependency.  

Also, I'd like to caution that depending on 3rd-party libraries is not 
always easy: just think about how much pain we suffer from the 
ever-changing asciidoc package, and the problems wit docbook xsl.

Ciao,
Dscho

Re: ambiguous git-log date and timestamp syntax

[Jakub Narebski]

On Sun, 2 Mar 2008, Johannes Schindelin wrote:
> On Sat, 1 Mar 2008, Jakub Narebski wrote:
> 
>> BTW. Git has few other such "reimplementing the wheel" things, like 
>> strbuf, or ALLOC_GROW, or it's own parseopt. I guess main reasons are to 
>> avoid adding yet another dependency, and that existing solutions doesn't 
>> fill all git needs.
> 
> Or that the existing wheels are quadratic wheels, and flat.

That's what I meant by "existing solutions don't fill all git needs".

> Just look at our own parse-options.[ch].  It is _still_ smaller and less 
> difficult to read than GNU getopt.  Yet, it is also much more powerful and 
> easier to use.

I meant here not only 'getopt', but also 'argp' (from libc), or 'popt'
library (used by rpm).

> Likewise, strbuf compares to Bstring, for example (although you might say 
> that Bstring is more powerful, but it comes at a price: it clutters the 
> namespace, and is not as performant as strbuf).

I vaguely recall something of discussion about this.

> ALLOC_GROW() is so small as to not merit any third-party dependency.  

True.

> Also, I'd like to caution that depending on 3rd-party libraries is not 
> always easy: just think about how much pain we suffer from the 
> ever-changing asciidoc package, and the problems wit docbook xsl.

I was rather thinking about something like git "dependency" on libXdiff,
namely having it embedded in git sources, perhaps as submodule, with git
specific improvements / changes / simplifications.


I wonder if it would be worthwhile to extract all those useful codelets
(mini libraries) like approxidate, strbuf, parseopt, ALLOC_GROW, 
list utils, etc. into separate micro-projects, to be able to be used
by other projects, for *them* not to have to reimplement the wheel.

Just a thought...
-- 
Jakub Narebski
Poland

Re: ambiguous git-log date and timestamp syntax

[Johannes Schindelin]

Hi,

On Sun, 2 Mar 2008, Jakub Narebski wrote:

> I wonder if it would be worthwhile to extract all those useful codelets 
> (mini libraries) like approxidate, strbuf, parseopt, ALLOC_GROW, list 
> utils, etc. into separate micro-projects, to be able to be used by other 
> projects, for *them* not to have to reimplement the wheel.

Actually, something like this happens in git-cheetah ATM, where I would 
like to use parts of libgit.a to call programs.

But then, I see the responsibility of separating out parts of libgit.a by 
those who want to use it, not by the git crowd.

Ciao,
Dscho

Re: ambiguous git-log date and timestamp syntax

[Florian Weimer]

* Jakub Narebski:

> I wonder how it compares with GNU date (from GNU Corutils) inexact date
> parsing (and why we couldn't lift the code from GNU date)...

I think the licenses are incompatible, you can't link that code to
OpenSSL.

[PATCH] Documentation: Remove --{min,max}-age option from git-log(1)

[Jakub Narebski]

The --max-age=<timestamp> and --min-age=<timestamp> are now shown only
in the git-rev-list manpage (plumbing).

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
 Documentation/rev-list-options.txt |    2 ++
 1 files changed, 2 insertions(+), 0 deletions(-)

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index a8138e2..c62ff49 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -130,9 +130,11 @@ limiting may be applied.
 
 	Show commits older than a specific date.
 
+ifdef::git-rev-list[]
 --max-age='timestamp', --min-age='timestamp'::
 
 	Limit the commits output to specified time range.
+endif::git-rev-list[]
 
 --author='pattern', --committer='pattern'::
 
-- 
1.5.4.2