Reproducible Timestamps

In some cases, it may be desirable to list a specific timestamp in the report. Timestamps are shown in the HTML Output, Coveralls JSON Output, and the Cobertura XML Output. This can be achieved via the --timestamp option or via Using SOURCE_DATE_EPOCH environment variable. This option does not affect the modification times or other filesystem metadata.

New in version 6.0: Respect environment variable SOURCE_DATE_EPOCH for default of gcovr --timestamp.

New in version 5.1: The gcovr --timestamp option.

Timestamp Syntax

The timestamp option understands different formats: Unix timestamps and RFC-3339 timestamps.

Unix timestamps (also known as Posix time or Epoch) are the number of seconds since 1 Jan 1970. These timestamps are always resolved in the UTC timezone. Example usage:

gcovr --timestamp 1640606727

RFC 3339 specifies a reasonable subset of ISO-8601 timestamps. This is the YYYY-MM-DDThh:mm:ss format, optionally followed by a timezone offset (+hh:mm, or Z for UTC). Example usage without a timezone:

gcovr --timestamp '2021-12-27 13:05:27'

Example usages that show equivalent specifications for UTC timestamps:

gcovr --timestamp '2021-12-27T13:05:27Z'
gcovr --timestamp '2021-12-27T13:05:27+00:00'
gcovr --timestamp '2021-12-27T13:05:27-00:00'

Differences and clarifications with respect to RFC-3339:

  • the time zone may be omitted
  • the date and time parts may be separated by a space character instead of the T
  • the date is parsed in a case insensitive manner
  • sub-second accuracy is not currently supported

Additional formats may be added in the future. To ensure that timestamps are handled in the expected manner, it is possible to select a particular timestamp syntax with a prefix.

  • Epoch timestamps can be selected with a @ or epoch: prefix.
  • RFC-3339 timestamps can be selected with a rfc3339: prefix.

Examples of prefixes:

gcovr --timestamp @1640606727
gcovr --timestamp epoch:1640606727
gcovr --timestamp 'rfc3339:2021-12-27 13:05:27'

Using timestamps from Git commits

As an example of using the timestamp feature, we might want to attribute a coverage report to the time when a Git commit was created. Git lets us extract the commit date from a commit with the git show command. For the current HEAD commit:

git show --no-patch --format=%cI HEAD

This can be combined into a Bash one-liner like this:

gcovr --timestamp="$(git show --no-patch --format=%cI HEAD)"

Each Git commit has two dates, the author date and the committer date. This information can be extracted with various format codes, e.g. %aI for the author date and %cI for the committer date. These format codes are also available in different formats. The supported Git formats are:

  • Unix timestamps: %at, %ct
  • “Strict ISO” format: %aI, %cI
  • depending on the --date option: %ad, %cd

Git’s --date option is documented in git log. The supported settings are:

  • Unix timestamps: --date=unix
  • “Strict ISO” format: --date=iso-strict, --date=iso8601-strict, --date=iso-strict-local, --date=iso8601-strict-local

Using SOURCE_DATE_EPOCH

The Reproducible Builds project defines the SOURCE_DATE_EPOCH variable. Gcovr will use this variable as a default timestamp if no explicit --timestamp is set.

The contents of this variable must be an UTC epoch, without any prefix. No other format is supported. Example usage:

SOURCE_DATE_EPOCH=1640606727 gcovr

For more information on setting and using this variable, see the Reproducible Builds documentation on SOURCE_DATE_EPOCH.