| Message ID | 20230201155712.86577-1-rafael@dulfer.be (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | rev-list: clarify git-log default date format | expand |
Rafael Dulfer <rafael@dulfer.be> writes: > From: Rafael Dulfer <rafael.dulfer@gmail.com> > > Currently, the documentation is slightly incomplete, not explaining all the differences the default format has with rfc2822. Leading to confusion for people trying to parse the date format outputted by git log > > This patch adds 2 more exceptions when compared to rfc2822. Also adds an example of what the format looks like (I originally wanted to specify this in strftime notation, but because of the way day-of-month is formatted this is impossible) Overly long lines. > > Signed-off-by: Rafael Dulfer <rafael.dulfer@gmail.com> > --- > Documentation/rev-list-options.txt | 10 ++++++++-- > 1 file changed, 8 insertions(+), 2 deletions(-) > > diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt > index ff68e48406..8bc8475f3e 100644 > --- a/Documentation/rev-list-options.txt > +++ b/Documentation/rev-list-options.txt > @@ -1103,9 +1103,15 @@ format placeholders. When using `-local`, the correct syntax is > `--date=default` is the default format, and is similar to > `--date=rfc2822`, with a few exceptions: > -- > - - there is no comma after the day-of-week > + - There is no comma after the day-of-week > > - - the time zone is omitted when the local time zone is used > + - The time zone is omitted when the local time zone is used > + > + - Day-of-month and month are switched around > + > + - Time-of-day and the year are switched around > + > +As a result, the format looks as follows: `Thu Jan 1 00:00:00 1970 +0000` with `+0000` being omitted when the local time zone is used. All of the above may technically be correct, but I wonder if it makes it easier to follow to simply stop saying "is similar to". That is The default format `--date=default` shows a single line with three-letter day of the week, three-letter month, day-of-month, hour-minute-second in the "HH:MM:SS" format, followed by 4-digit year, plus timezone information unless the local time zone is used (e.g. "Thu Jan 1 00:00:00 1970 +0000"). or something like that.
On Wed, Feb 01 2023, Junio C Hamano wrote: > Rafael Dulfer <rafael@dulfer.be> writes: > >> From: Rafael Dulfer <rafael.dulfer@gmail.com> >> >> Currently, the documentation is slightly incomplete, not explaining >> all the differences the default format has with rfc2822. Leading to >> confusion for people trying to parse the date format outputted by >> git log >> >> This patch adds 2 more exceptions when compared to rfc2822. Also >> adds an example of what the format looks like (I originally wanted >> to specify this in strftime notation, but because of the way >> day-of-month is formatted this is impossible) > > Overly long lines. > >> >> Signed-off-by: Rafael Dulfer <rafael.dulfer@gmail.com> >> --- >> Documentation/rev-list-options.txt | 10 ++++++++-- >> 1 file changed, 8 insertions(+), 2 deletions(-) >> >> diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt >> index ff68e48406..8bc8475f3e 100644 >> --- a/Documentation/rev-list-options.txt >> +++ b/Documentation/rev-list-options.txt >> @@ -1103,9 +1103,15 @@ format placeholders. When using `-local`, the correct syntax is >> `--date=default` is the default format, and is similar to >> `--date=rfc2822`, with a few exceptions: >> -- >> - - there is no comma after the day-of-week >> + - There is no comma after the day-of-week >> >> - - the time zone is omitted when the local time zone is used >> + - The time zone is omitted when the local time zone is used >> + >> + - Day-of-month and month are switched around >> + >> + - Time-of-day and the year are switched around >> + >> +As a result, the format looks as follows: `Thu Jan 1 00:00:00 1970 +0000` with `+0000` being omitted when the local time zone is used. > > All of the above may technically be correct, but I wonder if it > makes it easier to follow to simply stop saying "is similar to". > That is > > The default format `--date=default` shows a single line with > three-letter day of the week, three-letter month, day-of-month, > hour-minute-second in the "HH:MM:SS" format, followed by 4-digit > year, plus timezone information unless the local time zone is > used (e.g. "Thu Jan 1 00:00:00 1970 +0000"). > > or something like that. I think that following such a description in prose is still more confusing than just showing an example. E.g. we could say: Assuming a user in timezone +0200 (Central Europe) values of these `--date` argument would produce: |---------------+--------------------------------| | rfc2822 | Thu, 7 Apr 2005 15:13:13 -0700 | | rfc2822-local | Fri, 8 Apr 2005 00:13:13 +0200 | | default | Thu Apr 7 15:13:13 2005 -0700 | | default-local | Fri Apr 8 00:13:13 2005 | |---------------+--------------------------------| In particular your example says "unless the local time zone is used", but then shows an example that's 'default', not 'default-local'.
On Wed, Feb 01, 2023 at 10:19:02AM -0800, Junio C Hamano wrote: > > - - there is no comma after the day-of-week > > + - There is no comma after the day-of-week > > > > - - the time zone is omitted when the local time zone is used > > + - The time zone is omitted when the local time zone is used > > + > > + - Day-of-month and month are switched around > > + > > + - Time-of-day and the year are switched around > > + > > +As a result, the format looks as follows: `Thu Jan 1 00:00:00 1970 +0000` with `+0000` being omitted when the local time zone is used. > > All of the above may technically be correct, but I wonder if it > makes it easier to follow to simply stop saying "is similar to". > That is > > The default format `--date=default` shows a single line with > three-letter day of the week, three-letter month, day-of-month, > hour-minute-second in the "HH:MM:SS" format, followed by 4-digit > year, plus timezone information unless the local time zone is > used (e.g. "Thu Jan 1 00:00:00 1970 +0000"). > > or something like that. Yes, I agree with your suggestion. When you can explain something as "like X, but Y" it is helpful when Y is short. When it becomes much longer, than simply spelling out what X is becomes more helpful. -Peff
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: >> That is >> >> The default format `--date=default` shows a single line with >> three-letter day of the week, three-letter month, day-of-month, >> hour-minute-second in the "HH:MM:SS" format, followed by 4-digit >> year, plus timezone information unless the local time zone is >> used (e.g. "Thu Jan 1 00:00:00 1970 +0000"). >> >> or something like that. > > I think that following such a description in prose is still more > confusing than just showing an example. E.g. we could say: > > Assuming a user in timezone +0200 (Central Europe) values of Add "on day X at time Y" here, and I'd buy that ;-) > these `--date` argument would produce: > > |---------------+--------------------------------| > | rfc2822 | Thu, 7 Apr 2005 15:13:13 -0700 | > | rfc2822-local | Fri, 8 Apr 2005 00:13:13 +0200 | > | default | Thu Apr 7 15:13:13 2005 -0700 | > | default-local | Fri Apr 8 00:13:13 2005 | > |---------------+--------------------------------|
> Add "on day X at time Y" here, and I'd buy that
Rafael Dulfer <rafael@dulfer.be> writes: > like. "`--date=default` is the default format. It is a custom format > based on rfc2822". But the thing is it is *not* custom based on rfc2822. The default format came first, 2822 much later. If I have to guess (and I shouldn't because I was around back when we invented that format, but I am lazy and my recollecion hazy), it came straight from the result of ctime() but with timezone info appended at the end.
Junio C Hamano <gitster@pobox.com> writes: > Rafael Dulfer <rafael@dulfer.be> writes: > >> like. "`--date=default` is the default format. It is a custom format >> based on rfc2822". > > But the thing is it is *not* custom based on rfc2822. The default > format came first, 2822 much later. If I have to guess (and I > shouldn't because I was around back when we invented that format, > but I am lazy and my recollecion hazy), it came straight from the > result of ctime() but with timezone info appended at the end. It indeed was modeled after ctime() in f80cd783 (date.c: add "show_date()" function., 2005-05-06). date.c: add "show_date()" function. Kind of like ctime(), but not as broken.
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index ff68e48406..8bc8475f3e 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -1103,9 +1103,15 @@ format placeholders. When using `-local`, the correct syntax is `--date=default` is the default format, and is similar to `--date=rfc2822`, with a few exceptions: -- - - there is no comma after the day-of-week + - There is no comma after the day-of-week - - the time zone is omitted when the local time zone is used + - The time zone is omitted when the local time zone is used + + - Day-of-month and month are switched around + + - Time-of-day and the year are switched around + +As a result, the format looks as follows: `Thu Jan 1 00:00:00 1970 +0000` with `+0000` being omitted when the local time zone is used. ifdef::git-rev-list[] --header::