jimporter / mike

Manage multiple versions of your MkDocs-powered documentation via Git
BSD 3-Clause "New" or "Revised" License
534 stars 47 forks source link

Use `rfc2822` date format #99

Closed ktomk closed 2 years ago

ktomk commented 2 years ago

Changing git-fast-import(1) --date-format from raw to rfc22822 to support more GIT_COMMITTER_DATE date values.

PR: #100


Rationale:

In 2faa33c (Add support for GIT_COMMITTER_(NAME|EMAIL|DATE) env vars; resolves 98, 2022-04-27) the GIT_COMMITTER_DATE environment parameter was introduced.

The GIT_COMMITTER_DATE environment parameter ref supports three formats:

  1. Git internal format ref
  2. RFC 2822 ref
  3. ISO 8601 ref

The git-fast-import(1) ref comamnds --date-format option ref supports four Date formats ref of which two are interesting:

  1. Git internal format raw ref
  2. RFC 2822 rfc2822 ref

Currently in 2faa33c --date-format=raw is in use:

Unlike the rfc2822 format, this format is very strict. Any variation in formatting will cause fast-import to reject the value, and some sanity checks on the numeric values may also be performed.

This renders two out of three supported formats in GIT_COMMITTER_DATE as unsupported: RFC 2822 and ISO 8601, only the very strict Git internal format works.

On the other hand, when using git-fast-import(1) with --date-format=rfc2822, three out of three supported formats in GIT_COMMITTER_DATE are supported (100%), as it accepts both Git internal format as well as ISO 8601 as date formats.

Additionally in build context, raw does not support building at the beginning of the epoch (0 +0000), as with the Git internal format it must be after Jan 1, 2000 (git v0.99) / Mar 3 1973 (git v1.5.2.2). With rfc2822 it is possible to express this intend (Thu, 01 Jan 1970 00:00:00 +0000, 1970-01-01 00:00:00 +0000 etc.).


Notes:

  1. Tested against git v2.25.1
  2. Date format raw-permissive was not available with my version ("fatal: unknown --date-format argument raw-permissive") ref
  3. Date format now does not allow to specify the Git Comitter Date ("This is a toy format.") ref
  4. This improvement is to be suggested upstream to ghp-import: https://github.com/c-w/ghp-import/issues/108
  5. git_utils.make_whens time.time() reflecting SOURCE_DATE_EPOCH deferred