Re: [PATCH 2/2] Document date formats accepted by parse_date()

Nanako Shiraishi [off-list ref] writes:

Is there something wrong with 'show'?

  nana.git% ./test-date show '2005-04-07T22:13:13'
  2005-04-07T22:13:13 -> 40 years ago

Heh, you fooled me, and Peff is right.  "test-date show" does not
interpret its input any way other than as seconds-since-epoch.

I agree with the "native->internal" part of the suggestion.  What see by
default in "git show" output is merely the ctime(3) format followed by
timezone.  I don't mind if we call that "git native", even though I
suspect we do _not have to_ invent new word for that.

Also "test-date parse" seems to accept things like these:

    '2009.04.07 20:21:22 -0000'
    '04/07/2009 20:21:22 -0000'
    '07.04.2009 20:21:22 -0000'

---

On Wed, Dec 02, 2009 at 02:54:40PM -0800, Junio C Hamano [off-list ref] wrote:

I agree with the "native->internal" part of the suggestion.

Changed.

Also "test-date parse" seems to accept things like these:

    '2009.04.07 20:21:22 -0000'
    '04/07/2009 20:21:22 -0000'
    '07.04.2009 20:21:22 -0000'

Ah OK, I just tried 2009.04.07 (without the time part) and thought it
was about approxidate() as well. I added them.

 Documentation/date-formats.txt    |   26 ++++++++++++++++++++++++++
 Documentation/git-commit-tree.txt |    1 +
 Documentation/git-commit.txt      |    2 ++
 3 files changed, 29 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/date-formats.txt

diff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt
new file mode 100644
index 0000000..c000f08
--- /dev/null
+++ b/Documentation/date-formats.txt

@@ -0,0 +1,26 @@
+DATE FORMATS
+------------
+
+The GIT_AUTHOR_DATE, GIT_COMMITTER_DATE environment variables
+ifdef::git-commit[]
+and the `--date` option
+endif::git-commit[]
+support the following date formats:
+
+Git internal format::
+	It is `<unix timestamp> <timezone offset>`, where `<unix
+	timestamp>` is the number of seconds since the UNIX epoch.
+	`<timezone offset>` is a positive or negative offset from UTC.
+	For example CET (which is 2 hours ahead UTC) is `+0200`.
+
+RFC 2822::
+	The standard email format as described by RFC 2822, for example
+	`Thu, 07 Apr 2005 22:13:13 +0200`.
+
+ISO 8601::
+	Time and date specified by the ISO 8601 standard, for example
+	`2005-04-07T22:13:13`. The parser accepts a space instead of the
+	`T` character as well.
++
+NOTE: In addition, the date part is accepted in the following formats:
+`YYYY.MM.DD`, `MM/DD/YYYY` and `DD.MM.YYYY`.

diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index b8834ba..4fec5d5 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt

@@ -73,6 +73,7 @@ A commit comment is read from stdin. If a changelog
 entry is not provided via "<" redirection, 'git-commit-tree' will just wait
 for one to be entered and terminated with ^D.
 
+include::date-formats.txt[]
 
 Diagnostics
 -----------

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index cbbbeeb..17783b4 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt

@@ -220,6 +220,8 @@ specified.
 	these files are also staged for the next commit on top
 	of what have been staged before.
 
+:git-commit: 1
+include::date-formats.txt[]
 
 EXAMPLES
 --------

-- 
1.6.5.2