mirror of
https://https.git.savannah.gnu.org/git/gnulib.git
synced 2026-09-01 11:16:02 +00:00
105 lines
4.4 KiB
C
105 lines
4.4 KiB
C
/* Return the version-control based modification time of a file.
|
|
Copyright (C) 2025-2026 Free Software Foundation, Inc.
|
|
|
|
This program is free software: you can redistribute it and/or modify
|
|
it under the terms of the GNU General Public License as published by
|
|
the Free Software Foundation, either version 3 of the License, or
|
|
(at your option) any later version.
|
|
|
|
This program is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
GNU General Public License for more details.
|
|
|
|
You should have received a copy of the GNU General Public License
|
|
along with this program. If not, see <https://www.gnu.org/licenses/>. */
|
|
|
|
/* Written by Bruno Haible <bruno@clisp.org>, 2025. */
|
|
|
|
#ifndef _VC_MTIME_H
|
|
#define _VC_MTIME_H
|
|
|
|
/* Get struct timespec. */
|
|
#include <time.h>
|
|
|
|
/* The "version-controlled modification time" vc_mtime(F) of a file F
|
|
is defined as:
|
|
- If F is under version control and not modified locally:
|
|
the time of the last change of F in the version control system.
|
|
- Otherwise: The modification time of F on disk.
|
|
|
|
For now, the only VCS supported by this module is git. (hg and svn are
|
|
hardly in use any more.)
|
|
|
|
This has the properties that:
|
|
- Different users who have checked out the same git repo on different
|
|
machines, at different times, and not done local modifications,
|
|
get the same vc_mtime(F).
|
|
- If a user has modified F locally, the modification time of that file
|
|
counts.
|
|
- If that user then reverts the modification, they then again get the
|
|
same vc_mtime(F) as everyone else.
|
|
- Different users who have unpacked the same tarball (without .git
|
|
directory) on different machines, at different times, also get the same
|
|
vc_mtime(F) [but possibly a different one than when the .git directory
|
|
was present]. (Assuming a POSIX compliant file system.)
|
|
- When a user commits local modifications into git, this only increases
|
|
(not decreases) the vc_mtime(F).
|
|
|
|
The purpose of the version-controlled modification time is to produce a
|
|
reproducible timestamp(Z) of a file Z that depends on files X1, ..., Xn,
|
|
in such a way that
|
|
- timestamp(Z) is reproducible, that is, different users on different
|
|
machines get the same value.
|
|
- timestamp(Z) is related to reality. It's not just a dummy, like what
|
|
is suggested in <https://reproducible-builds.org/docs/timestamps/>.
|
|
- One can arrange for timestamp(Z) to respect the modification time
|
|
relations of a build system.
|
|
|
|
There are two uses of such a timestamp:
|
|
- It can be set as the modification time of file Z in a file system, or
|
|
- It can be embedded in Z, with the purpose of telling a user how old
|
|
the file Z is. For example, in PDF files or in generated documentation,
|
|
such a time is embedded in a special place.
|
|
|
|
The simplest example is a file Z that depends on files X1, ..., Xn.
|
|
Generally one will define
|
|
timestamp(Z) = max (vc_mtime(X1), ..., vc_mtime(Xn))
|
|
for an embedded timestamp, or
|
|
timestamp(Z) = max (vc_mtime(X1), ..., vc_mtime(Xn)) + 1 second
|
|
for a time stamp in a file system. The added second
|
|
1. accounts for fractional seconds in mtime(X1), ..., mtime(Xn),
|
|
2. allows for 'make' implementation that attempt to rebuild Z
|
|
if mtime(Z) == mtime(Xi).
|
|
|
|
A more complicated example is when there are intermediate built files, not
|
|
under version control. For example, if the build process produces
|
|
X1, X2 -> Y1
|
|
X3, X4 -> Y2
|
|
Y1, Y2, X5 -> Z
|
|
where Y1 and Y2 are intermediate built files, you should ignore the
|
|
mtime(Y1), mtime(Y2), and consider only the vc_mtime(X1), ..., vc_mtime(X5).
|
|
*/
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/* Determines the version-controlled modification time of FILENAME, stores it
|
|
in *MTIME, and returns 0.
|
|
Upon failure, it returns -1. */
|
|
extern int vc_mtime (struct timespec *mtime, const char *filename);
|
|
|
|
/* Determines the maximum of the version-controlled modification times of
|
|
FILENAMES[0..NFILES-1], and returns 0.
|
|
Upon failure, it returns -1.
|
|
NFILES must be > 0. */
|
|
extern int max_vc_mtime (struct timespec *max_of_mtimes,
|
|
size_t nfiles, const char * const *filenames);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* _VC_MTIME_H */
|