[PATCH] CodingGuidelines: st_mtimespec vs st_mtim vs st_mtime

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 10, 2026, 18:10 UTC
Message-ID: <xmqqzf3aofdj.fsf_-_@gitster.g>
In-Reply-To: <xmqqo6jqpzxv.fsf@gitster.g>

Most unfortunately macOS does not support st_[amc]tim for timestamps down to nanosecond resolution as POSIX systems.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/CodingGuidelines | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git c/Documentation/CodingGuidelines w/Documentation/CodingGuidelines
index 4992e52093..4e54139fd7 100644
--- c/Documentation/CodingGuidelines
+++ w/Documentation/CodingGuidelines
@@ -693,6 +693,12 @@ For C programs:
          char *dogs[] = ...;
          walk_all_dogs(dogs);
 
+ - For file timestamps, do not use "st_mtim" (and other timestamp
+   members in "struct stat") unconditionally; not everybody is POSIX
+   (grep for USE_ST_TIMESPEC).  If you only need timestamp in whole
+   second resolution, "st_mtime" should work fine everywhere.
+
+
 For Perl programs:
 
  - Most of the C guidelines above apply.