The Context

While preparing a Git repository for my tutorial “The Disappearance of J. T. Womblegast — A Git Tutorial” for the Agile Testing Days 2024, I wanted to set the commit and author date for commits explicitly.

In most cases, these dates are identical. Still, they can be different, as the author and committer can be different people (for details about the commit details, see the extensive Git documentation for commits). One interesting detail about the dates: The author date can be set with the command line option --date , while the committer date can only be set using an environment variable.

How to set the dates

I chose to set the author date using the command line option and the environment variable GIT_COMMITTER_DATE for the committer date.

When there is a change in the Git index (or staging area), here’s how to commit it with the given date and time info:

> GIT_COMMITTER_DATE="Sun Aug 4 11:14:08 2024 +0200" git commit -m "Demo commit" --date "Wed Jul 24 19:09:11 2024 +0200"
[main (root-commit) cbaea5e] Demo commit
 Date: Wed Jul 24 19:09:11 2024 +0200
 1 file changed, 1 insertion(+)
 create mode 100644 wahoodie

All is good: I created a file with some content, added it to the staging area, and committed it.

Varying the dates

Let’s be more daring with the commit dates and go a few years into the future and past. Add some more text to the file ‘wahoodie’ I used before, add the change to the Git index and commit:

> echo "more text" >> wahoodie
> git add .
> GIT_COMMITTER_DATE="Sat Jan 1 00:00:00 2000 +0200" git commit -m "Another commit" --date "Tue Jan 19 2038 03:14:08 UTC"
[main 133c21b] Demo commit
 Date: Tue Jan 19 03:14:08 2038 +0000
 1 file changed, 1 insertion(+)

It still looks good.

When it’s not working

Now, let’s go far into the past (and future):

> echo "another line" >> wahoodie
> git add .
> GIT_COMMITTER_DATE="Wed 11 Oct 1634 22:47:38 +0000" git commit -m "Updates file" --date "Tue Jan 19 2038 03:14:08 UTC"
fatal: invalid date format: Wed 11 Oct 1634 22:47:38 +0000

Huh? Is something wrong with the (committer) date? It looks OK, but it could be the weekday that’s causing trouble. Let’s try to commit a change using the wrong weekdays:

> echo "even more text" >> wahoodie
> git add .
> GIT_COMMITTER_DATE="Mon Aug 4 11:14:08 2024 +0200" git commit -m "Demo commit" --date "Sun Jul 24 19:09:11 2024 +0200"
[main e2e848e] Demo commit
 Date: Wed Jul 24 19:09:11 2024 +0200
 1 file changed, 1 insertion(+)
stephan@seaside ~/dev/garble-git-repo/tmp/wahoodie ᚠ main > git log --format="Author Date:    %ad %nCommitter Date: %cd     %h" -1
Author Date:    Wed Jul 24 19:09:11 2024 +0200
Committer Date: Sun Aug 4 11:14:08 2024 +0200     e2e848e

The given date is used, and the offered weekday was corrected. Things look OK when leaving out the weekday altogether:

> echo "one more line" >> wahoodie
> git add .
> GIT_COMMITTER_DATE="Aug 4 11:14:08 1987 +0200" git commit -m "further update" --date "Jul 24 2042 19:09:11 +0200"
[main 696dc2b] further update
 Date: Thu Jul 24 19:09:11 2042 +0200
 1 file changed, 1 insertion(+)
> git log --format="Author Date:    %ad %nCommitter Date: %cd     %h" -1
Author Date:    Thu Jul 24 19:09:11 2042 +0200
Committer Date: Tue Aug 4 11:14:08 1987 +0200     696dc2b

The real cause of the error message

After experimenting with the date & talking to folks on the Git Discord, I figured the epoch is the (lower) boundary for dates in Git. Let’s use the following shell script (‘demo-date-format-issue.sh’):

git init tmp
cd tmp
echo "Some content" > non-empty-file.txt
git add .
GIT_COMMITTER_DATE="31 Dec 1969 23:59:60 +0000" git commit -m "Commit 1" --date "12 Dec 1969 23:59:60 +0000"
GIT_COMMITTER_DATE="01 Jan 1970 00:00:00 +0000" git commit -m "Commit 1" --date "01 Jan 1970 00:00:00 +0000"

Running it gives the following output:

> ./demo-date-format-issue.sh
Initialized empty Git repository in /Users/stephan/dev/garble-git-repo/tmp/.git/
fatal: invalid date format: 31 Dec 1969 23:59:60 +0000
[main (root-commit) 9c0b65a] Commit 1
 Date: Thu Jan 1 00:00:00 1970 +0000
 1 file changed, 1 insertion(+)
 create mode 100644 non-empty-file.txt

Aha! The first commit attempt fails and gives a misleading error message: The date format is perfectly valid. Apparently, Git can’t process a date before 1 January 1970 00:00:00 UTC.

Remarkably, the next date that might cause trouble, ‘2038-01-19T03:14:08+00:00’, doesn’t. Instead, the last future date & time at which a commit is possible is ‘2099-12-31T23:59:59+00:00’, as the following example code shows:

echo "More content" > non-empty-file.txt
git add .
GIT_COMMITTER_DATE="01 Jan 2100 00:00:00 +0000" git commit -m "Commit 2" --date "01 Jan 2100 00:00:00 +0000"
GIT_COMMITTER_DATE="31 Dec 2099 23:59:60 +0000" git commit -m "Commit 2" --date "31 Dec 2099 23:59:60 +0000"

The output of this is:

fatal: invalid date format: 01 Jan 2100 00:00:00 +0000

I don’t understand why the year change from 2099 to 2100 is the upper boundary for the dates Git will process. To me, this seems a bit limiting since it’s ‘just’ ≈75½ years until then. (If you know why this limit has been chosen, please share.)

In any case, printing an error message that claims a date format is invalid when it’s not is a bug. I said ‘obscure bug’ in the title. 😃

I reported the issue in the Git mailing list, but am not sure about how thigs develop from here. Someone proposed a better error message and I very much appreciate it.