[PATCH v3 0/3] Convert USE_NSEC to runtime config

["D. Ben Knoble" <ben.knoble@gmail.com>]

Topic name: dk/use-nsec-runtime (applied)

Topic summary: Expose USE_NSEC as a runtime configuration, since
build-time is too early for distributing Git [1]. As a result, common
index-related options, like git-diff, are less likely to hit "racy git"
problems on supported filesystems.

[1]: https://git.github.io/rev_news/2026/07/31/edition-137/

Built on master (2c78326f81 (The 11th batch, 2026-08-05)).

Changes in v3:

- #ifdef out use_nanosec when NO_NSEC is requested

As I have heard no comments about the "Todo" lines below, which perhaps
could more clearly be marked "RFC"/"RFH", I've added this line to call
them out ;) and renamed them "Comments welcome"

Changes in v2:

- move Best-viewed-with trailer into message body as descriptive
  text.
- read core.useNanosec through struct repo instead of parsing
  config strings. The test suite passes locally this way, though that
  skipped 151 tests.
    - CI run: https://github.com/benknoble/git/actions/runs/31701945211

Original cover letter:

Hi all, this series follows up on the previous racy Git/USE_NSEC
conversations.

- The first patch is a mostly-unrelated documentation fix for Meson, but
  it came out of something I spotted while reviewing the outputs of the
  final (main) patch.
- The second patch is a preliminary no-op reorganization of
  repo_config_values_init.
- The third patch is the meat, converting USE_NSEC into core.useNanosec.

There is a small textual and semantic conflict with
'ty/repo-config-cleanups' in 'seen', since that branch removes the
comments in 'struct repo_config_values' which this series adds to. (The
semantic conflict is that, if we drop those comments, we should probably
not add them to repo_config_values_init like I do in patch 2.)

Comments welcome: I haven't touched any tests; I saw a bunch of hits for
"git grep racy t" but wasn't sure how to fit this particular change in,
especially since it won't be equally valid on all systems? Advice
welcome.

Comments welcome: I wonder if "useNanosec" paints us into too much of a
corner; that is (slightly more abstractly), we are using *extended
precision* in the index. Maybe the name and documentation should reflect
that, so we aren't too committed to "nanoseconds"?
    - Some platforms could offer extended precision that is not as
      precise as nanoseconds
    - Some could offer precision _beyond_ nanoseconds

idk.

v1: <cover.1786103607.git.ben.knoble@gmail.com>
v2: <cover.1786710807.git.ben.knoble@gmail.com>

[1/3] meson: expose knob for xmlto relative links in manuals
[2/3] environment: align repo_config_values_init with struct declaration
[3/3] core: convert build-time USE_NSEC into runtime core.useNanosec

 Documentation/config/core.adoc        |  6 ++++++
 Documentation/meson.build             |  7 ++++++-
 Documentation/technical/racy-git.adoc | 11 +++++-----
 Makefile                              | 12 +----------
 builtin/update-index.c                |  2 +-
 compat/posix.h                        |  1 -
 configure.ac                          |  6 ------
 environment.c                         | 29 ++++++++++++++++++++-------
 environment.h                         |  1 +
 meson_options.txt                     |  2 ++
 read-cache.c                          | 16 ++++++++++-----
 statinfo.c                            | 14 +++++++------
 12 files changed, 64 insertions(+), 43 deletions(-)

Diff-intervalle contre v2 :
1:  d612de6c2d = 1:  d612de6c2d meson: expose knob for xmlto relative links in manuals
2:  5693baa992 = 2:  5693baa992 environment: align repo_config_values_init with struct declaration
3:  2d1424732a ! 3:  48fceb4b57 core: convert build-time USE_NSEC into runtime core.useNanosec
    @@ Commit message
     
      ## Notes (benknoble/commits) ##
         Related benchmarks: <https://lore.kernel.org/git/CALnO6CBm4g27mWBvD9m6yL0e5YZu3M9_zcUeLZk7QwTgnxMLQA@mail.gmail.com/>
    -    CI: <https://github.com/benknoble/git/actions/runs/31701945211>
    +    CI: <https://github.com/benknoble/git/actions/runs/32137191115>
    +
    +    v3:
    +        We could perhaps be cute in read-cache.c:is_racy_stat() by writing
    +        the preprocessor directive like
    +
    +    		return (istate->timestamp.sec &&
    +    	#ifndef NO_NSEC
    +    			/* nanosecond timestamped files can also be racy! */
    +    			use_nsec
    +    			? (istate->timestamp.sec < sd->sd_mtime.sec ||
    +    			   (istate->timestamp.sec == sd->sd_mtime.sec &&
    +    			    istate->timestamp.nsec <= sd->sd_mtime.nsec))
    +    			:
    +    	#endif
    +    			istate->timestamp.sec <= sd->sd_mtime.sec
    +
    +        but that seemed maybe too clever?
     
      ## Documentation/config/core.adoc ##
     @@ Documentation/config/core.adoc: core.trustctime::
    @@ environment.c: int git_default_core_config(const char *var, const char *value,
      		return 0;
      	}
      
    ++#ifndef NO_NSEC
     +	if (!strcmp(var, "core.usenanosec")) {
     +		cfg->use_nanosec = git_config_bool(var, value);
     +		return 0;
     +	}
    ++#endif
     +
      	/* Add other config variables here and to Documentation/config.adoc. */
      	return platform_core_config(var, value, ctx, cb);
    @@ environment.c: void repo_config_values_init(struct repo_config_values *cfg)
      	cfg->ignore_case = 0;
      	cfg->trust_executable_bit = 1;
      	cfg->has_symlinks = platform_has_symlinks();
    ++#ifndef NO_NSEC
     +	cfg->use_nanosec = 0;
    ++#endif
      
      	/* section "sparse" config values */
      	cfg->sparse_expect_files_outside_of_patterns = 0;
    @@ read-cache.c: static int ce_match_stat_basic(const struct cache_entry *ce, struc
      static int is_racy_stat(const struct index_state *istate,
      			const struct stat_data *sd)
      {
    ++#ifndef NO_NSEC
     +	int use_nsec = repo_config_values(istate->repo)->use_nanosec;
    ++#endif
     +
      	return (istate->timestamp.sec &&
     -#ifdef USE_NSEC
    @@ read-cache.c: static int ce_match_stat_basic(const struct cache_entry *ce, struc
     -		(istate->timestamp.sec < sd->sd_mtime.sec ||
     -		 (istate->timestamp.sec == sd->sd_mtime.sec &&
     -		  istate->timestamp.nsec <= sd->sd_mtime.nsec))
    --#else
    --		istate->timestamp.sec <= sd->sd_mtime.sec
    --#endif
    ++#ifndef NO_NSEC
     +		/* nanosecond timestamped files can also be racy! */
     +		use_nsec
     +		? (istate->timestamp.sec < sd->sd_mtime.sec ||
     +		   (istate->timestamp.sec == sd->sd_mtime.sec &&
     +		    istate->timestamp.nsec <= sd->sd_mtime.nsec))
     +		: istate->timestamp.sec <= sd->sd_mtime.sec
    - 		);
    - }
    - 
    + #else
    + 		istate->timestamp.sec <= sd->sd_mtime.sec
    + #endif
     
      ## statinfo.c ##
     @@ statinfo.c: int match_stat_data(const struct stat_data *sd, struct stat *st)
    @@ statinfo.c: int match_stat_data(const struct stat_data *sd, struct stat *st)
     -	if (cfg->trust_ctime && cfg->check_stat &&
     -	    sd->sd_ctime.nsec != ST_CTIME_NSEC(*st))
     -		changed |= CTIME_CHANGED;
    --#endif
    ++#ifndef NO_NSEC
     +	if (cfg->use_nanosec) {
     +		if (cfg->check_stat && sd->sd_mtime.nsec != ST_MTIME_NSEC(*st))
     +			changed |= MTIME_CHANGED;
    @@ statinfo.c: int match_stat_data(const struct stat_data *sd, struct stat *st)
     +		    sd->sd_ctime.nsec != ST_CTIME_NSEC(*st))
     +			changed |= CTIME_CHANGED;
     +	}
    + #endif
      
      	if (cfg->check_stat) {
    - 		if (sd->sd_uid != (unsigned int) st->st_uid ||

base-commit: 2c78326f810173a4f3aefd8021f1e07575412481
-- 
2.55.0.860.g4b6b3295ed.dirty