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
@
orepoch:
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.