gcovr · Spacetown · Feb 22, 2023 · Feb 22, 2023 · Feb 22, 2023 · Feb 22, 2023
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -33,6 +33,7 @@ New features and notable changes:
 - Allow annotations for never executed branches. (:issue:`711`)
 - Add function merge mode for same function defined in different lines. (:issue:`700`)
 - Update link to gcovr documentation in HTML report to point to the documentation of the used version. (:issue:`723`)
+- Add environment `SOURCE_DATE_EPOCH <https://reproducible-builds.org/docs/source-date-epoch>`_ to set default for :option:`--timestamp`. (:issue:`729`)
 
 Bug fixes and small improvements:
 

diff --git a/doc/examples/example_timestamps.sh b/doc/examples/example_timestamps.sh
@@ -6,6 +6,10 @@ set -x  # trace all commands
 gcovr --timestamp 1640606727
 #END simple epoch
 
+#BEGIN source date epoch
+SOURCE_DATE_EPOCH=1640606727 gcovr
+#END source date epoch
+
 #BEGIN simple RFC 3339
 gcovr --timestamp '2021-12-27 13:05:27'
 #END simple RFC 3339

diff --git a/doc/source/guide/timestamps.rst b/doc/source/guide/timestamps.rst
@@ -5,12 +5,15 @@ Reproducible Timestamps
 
 In some cases, it may be desirable to list a specific timestamp in the report.
 Timestamps are shown in
-the :ref:`html_output`,
-:ref:`coveralls_output`,
-and the :ref:`cobertura_output`.
-This can be achieved via the :option:`--timestamp <gcovr --timestamp>` option.
+the :ref:`html_output`, :ref:`coveralls_output`, and the :ref:`cobertura_output`.
+This can be achieved via the :option:`--timestamp <gcovr --timestamp>` option
+or via :ref:`Using SOURCE_DATE_EPOCH` environment variable.
 This option does not affect the modification times or other filesystem metadata.
 
+.. versionadded:: NEXT
+
+   Respect environment variable `SOURCE_DATE_EPOCH`_ for default of :option:`gcovr --timestamp`.
+
 .. versionadded:: 5.1
 
    The :option:`gcovr --timestamp` option.
@@ -112,3 +115,27 @@ The supported settings are:
   ``--date=iso8601-strict``,
   ``--date=iso-strict-local``,
   ``--date=iso8601-strict-local``
+
+.. _Using SOURCE_DATE_EPOCH:
+
+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 :option:`--timestamp <gcovr --timestamp>` is set.
+
+The contents of this variable *must* be an UTC epoch, without any prefix.
+No other format is supported.
+Example usage:
+
+.. include:: ../../examples/example_timestamps.sh
+   :code: bash
+   :start-after: #BEGIN source date epoch
+   :end-before: #END source date epoch
+
+For more information on setting and using this variable,
+see the `Reproducible Builds documentation on SOURCE_DATE_EPOCH
+<SOURCE_DATE_EPOCH_>`_.
+
+.. _SOURCE_DATE_EPOCH: https://reproducible-builds.org/docs/source-date-epoch/
diff --git a/gcovr/configuration.py b/gcovr/configuration.py
@@ -21,6 +21,7 @@
 from argparse import ArgumentParser, ArgumentTypeError, SUPPRESS
 from inspect import isclass
 from locale import getpreferredencoding
+import logging
 from multiprocessing import cpu_count
 from typing import Iterable, Any, List, Optional, Union, Callable, TextIO, Dict
 from dataclasses import dataclass
@@ -31,6 +32,8 @@
 from .utils import FilterOption, force_unix_separator
 from .writer.html import CssRenderer
 
+logger = logging.getLogger("gcovr")
+
 
 def check_percentage(value: str) -> float:
     r"""
@@ -94,6 +97,50 @@ def timestamp(value: str) -> datetime.datetime:
         raise ArgumentTypeError(f"{ex}: {value!r}") from None
 
 
+def source_date_epoch() -> Optional[datetime.datetime]:
+    """
+    Load time from SOURCE_DATE_EPOCH, if it exists.
+    See: <https://reproducible-builds.org/docs/source-date-epoch/>
+
+    Examples:
+    >>> monkeypatch = getfixture("monkeypatch")
+    >>> caplog = getfixture("caplog")
+
+    Example: can be empty
+    >>> with monkeypatch.context() as mp:
+    ...   mp.delenv("SOURCE_DATE_EPOCH", raising=False)
+    ...   print(source_date_epoch())
+    None
+
+    Example: can contain timestamp
+    >>> with monkeypatch.context() as mp:
+    ...   mp.setenv("SOURCE_DATE_EPOCH", "1677067226")
+    ...   print(source_date_epoch())
+    2023-02-22 12:00:26+00:00
+
+    Example: can contain invalid timestamp
+    >>> with monkeypatch.context() as mp:
+    ...   mp.setenv("SOURCE_DATE_EPOCH", "not a timestamp")
+    ...   print(source_date_epoch())
+    None
+    >>> for m in caplog.messages: print(m)
+    Ignoring invalid environment variable SOURCE_DATE_EPOCH='not a timestamp'
+    """
+
+    ts = os.environ.get("SOURCE_DATE_EPOCH")
+
+    if ts:
+        try:
+            return datetime.datetime.fromtimestamp(int(ts), datetime.timezone.utc)
+        except Exception:
+            logger.warning(
+                "Ignoring invalid environment variable SOURCE_DATE_EPOCH=%r",
+                ts,
+            )
+
+    return None
+
+
 class OutputOrDefault:
     """An output path that may be empty.
 
@@ -1160,10 +1207,12 @@ def merge_options_and_set_defaults(
             "Override current time for reproducible reports. "
             "Can use `YYYY-MM-DD hh:mm:ss` or epoch notation. "
             "Used by HTML, Coveralls, and Cobertura reports. "
-            "Default: current time."
+            "Default: Environment variable SOURCE_DATE_EPOCH "
+            "(see https://reproducible-builds.org/docs/source-date-epoch) "
+            "or current time."
         ),
         type=timestamp,
-        default=datetime.datetime.now(),
+        default=source_date_epoch() or datetime.datetime.now(),
     ),
     GcovrConfigOption(
         "filter",