[This is a resubmission of https://lists.gnu.org/archive/html/help-tar/2016-01/msg00000.html]

This feature is desired by important users of tar for reproducible
archive creation (e.g., dpkg-dev -- see
<https://bugs.debian.org/759999#20>).  It is intended in the same
spirit as other features in GNU tar (e.g., --exclude-vcs-ignores) that
offer simple ways to handle common use cases related to software
development and distribution.

The new `--clamp-mtime` option will change the behavior of `--mtime` to
only use the time specified if the file mtime is newer than the given time.
The `--clamp-mtime` option can only be used together with `--mtime`.

This addresses a common scenario: a software distributor wants to ship
compiled binaries, but the package shipped should also include some
files copied directly from the source distribution (e.g. config files,
etc).  At the same time, we'd like the archive in question to be
"reproducible" where possible -- getting a byte-for-byte identical
match upon rebuild.  See <https://reproducible-builds.org/> for more
information.

With this feature, a reproducible tarball can be created by noting the
time just before the build (either via $(date) or some pre-build
artifact like a revision control system or changelog), and then
bounding the mtimes in the resulting archive via --clamp-mtime.

In order to implement the option, we transform `set_mtime_option` from
a bool to an enum with three values: use original file mtime, force all mtimes
to be of the same value, and clamp mtimes (as explained above).

To verify that `--clamp-mtime` is used together with `--mtime`, `mtime_option`
is now initialized to a minimal value as done for `newer_mtime_option`. As
the same macro can now be used for both options, NEWER_OPTION_INITIALIZED
has been renamed to TIME_OPTION_INITIALIZED.

Documentation and the test suite have also been updated.
---
 doc/tar.1          |  5 ++++-
 doc/tar.texi       | 21 +++++++++++++++++++++
 src/common.h       | 17 ++++++++++++-----
 src/create.c       | 15 ++++++++++++++-
 src/list.c         |  2 +-
 src/tar.c          | 23 ++++++++++++++++++++---
 tests/Makefile.am  |  1 +
 tests/testsuite.at |  1 +
 tests/time02.at    | 42 ++++++++++++++++++++++++++++++++++++++++++
 9 files changed, 116 insertions(+), 11 deletions(-)