Re: [PATCH v3] ignore: note info/exclude lives in GIT_COMMON_DIR, not GIT_DIR

[Phillip Wood <phillip.wood123@gmail.com>]

Hi Ben

On 12/05/2026 22:21, D. Ben Knoble wrote:
> gitignore(5) says that the per-repository ignore file is
> $GIT_DIR/info/exclude, but in a worktree that is not the case:
> 
>      git rev-parse --git-path info/exclude
>      /path/to/main/worktree/.git/info/exclude
>      git rev-parse --git-common-dir
>      /path/to/main/worktree/.git
> 
> We actually use $GIT_COMMON_DIR/info/exclude. Adjust the documentation
> and some code comments to say so.

Thanks for the re-roll, this looks good to me

Phillip

> Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
> ---
> 
> Notes (benknoble/commits):
>      Changes in v3:
>      
>      Adjust more occurrences
>      
>      Link to v2: <d58b6e921d3005c6170fc6c47f175214acb3fa68.1778249267.git.ben.knoble+github@gmail.com>
>      
>      Changes in v2:
>      
>      Only adjust the documentation.
>      
>      brian points out that a more general extension would allow using more
>      info/ files as "per-worktree," which I don't have the impetus to
>      implement myself.
>      
>      Phillip and Junio asked for a concrete use case:
>      
>          A colleague is developing a tool for managing the "skill files" of
>          various LLM tools (Claude, Windsurf, etc.). The files have
>          requirements that make it hard to generically ignore them (e.g.,
>          filenames and front-matter have to match), but different tasks
>          (corresponding to worktrees) may want different active skills, so it
>          is desirable to ignore the files. Think of this like node_modules.
>      
>          Unfortunately, since per-worktree ignores don't work, the current
>          solution is to put a .gitignore file in the corresponding directory
>          with the installed skills that ignores itself and the installed
>          skills.
>      
>      Since overall reactions seem fairly negative (or require a more general
>      extension, which I think is probably the right course but not simply
>      implemented), I've opted to adjust the docs. They originally confused
>      me, as I was surprised when my colleague reported that per-worktree
>      ignores didn't work (the docs imply they should by use of $GIT_DIR).
>      
>      Link to v1: <e3ee0a11b566dd2cc605447c111ae4620bce0fe6.1777050300.git.ben.knoble+github@gmail.com>
>      
>      v1 notes:
>      
>      Discussed briefly at https://lore.kernel.org/git/CALnO6CCXmA+ATT7CuyWkU6P8qmLCCpMi5Ppr1c78s0heznpVyw@mail.gmail.com/T
>      
>      This is based on next (4f69b47b94 (Merge branch 'ps/test-set-e-clean'
>      into next, 2026-04-23)) but cleanly applies to master (94f057755b (Git
>      2.54, 2026-04-19)) and seen (50541634cb (Merge branch
>      'js/parseopt-subcommand-autocorrection' into seen, 2026-04-23)).
> 
>   Documentation/git-ls-files.adoc    |  2 +-
>   Documentation/git-svn.adoc         |  2 +-
>   Documentation/gitformat-index.adoc |  4 ++--
>   Documentation/gitignore.adoc       | 12 ++++++------
>   dir.c                              |  4 ++--
>   dir.h                              |  2 +-
>   6 files changed, 13 insertions(+), 13 deletions(-)
> 
> diff --git a/Documentation/git-ls-files.adoc b/Documentation/git-ls-files.adoc
> index 58c529afbe..2b175388e1 100644
> --- a/Documentation/git-ls-files.adoc
> +++ b/Documentation/git-ls-files.adoc
> @@ -331,7 +331,7 @@ can give `--exclude-per-directory=.gitignore`, and then specify:
>     1. The file specified by the `core.excludesfile` configuration
>        variable, if exists, or the `$XDG_CONFIG_HOME/git/ignore` file.
>   
> -  2. The `$GIT_DIR/info/exclude` file.
> +  2. The `$GIT_COMMON_DIR/info/exclude` file.
>   
>   via the `--exclude-from=` option.
>   
> diff --git a/Documentation/git-svn.adoc b/Documentation/git-svn.adoc
> index c26c12bab3..2a7fa60465 100644
> --- a/Documentation/git-svn.adoc
> +++ b/Documentation/git-svn.adoc
> @@ -439,7 +439,7 @@ Any other arguments are passed directly to 'git log'
>   'show-ignore'::
>   	Recursively finds and lists the svn:ignore and svn:global-ignores
>   	properties on directories. The output is suitable for appending to
> -	the $GIT_DIR/info/exclude file.
> +	the $GIT_COMMON_DIR/info/exclude file.
>   
>   'mkdirs'::
>   	Attempts to recreate empty directories that core Git cannot track
> diff --git a/Documentation/gitformat-index.adoc b/Documentation/gitformat-index.adoc
> index 145cace1fe..f6a427cb49 100644
> --- a/Documentation/gitformat-index.adoc
> +++ b/Documentation/gitformat-index.adoc
> @@ -291,14 +291,14 @@ Git index format
>       sequence in variable width encoding. Each string describes the
>       environment where the cache can be used.
>   
> -  - Stat data of $GIT_DIR/info/exclude. See "Index entry" section from
> +  - Stat data of $GIT_COMMON_DIR/info/exclude. See "Index entry" section from
>       ctime field until "file size".
>   
>     - Stat data of core.excludesFile
>   
>     - 32-bit dir_flags (see struct dir_struct)
>   
> -  - Hash of $GIT_DIR/info/exclude. A null hash means the file
> +  - Hash of $GIT_COMMON_DIR/info/exclude. A null hash means the file
>       does not exist.
>   
>     - Hash of core.excludesFile. A null hash means the file does
> diff --git a/Documentation/gitignore.adoc b/Documentation/gitignore.adoc
> index a3d24e5c34..7979e50f18 100644
> --- a/Documentation/gitignore.adoc
> +++ b/Documentation/gitignore.adoc
> @@ -7,7 +7,7 @@ gitignore - Specifies intentionally untracked files to ignore
>   
>   SYNOPSIS
>   --------
> -$XDG_CONFIG_HOME/git/ignore, $GIT_DIR/info/exclude, .gitignore
> +$XDG_CONFIG_HOME/git/ignore, $GIT_COMMON_DIR/info/exclude, .gitignore
>   
>   DESCRIPTION
>   -----------
> @@ -34,7 +34,7 @@ precedence, the last matching pattern decides the outcome):
>      includes such `.gitignore` files in its repository, containing patterns for
>      files generated as part of the project build.
>   
> - * Patterns read from `$GIT_DIR/info/exclude`.
> + * Patterns read from `$GIT_COMMON_DIR/info/exclude`.
>   
>    * Patterns read from the file specified by the configuration
>      variable `core.excludesFile`.
> @@ -50,7 +50,7 @@ be used.
>      specific to a particular repository but which do not need to be shared
>      with other related repositories (e.g., auxiliary files that live inside
>      the repository but are specific to one user's workflow) should go into
> -   the `$GIT_DIR/info/exclude` file.
> +   the `$GIT_COMMON_DIR/info/exclude` file.
>   
>    * Patterns which a user wants Git to
>      ignore in all situations (e.g., backup or temporary files generated by
> @@ -97,7 +97,7 @@ PATTERN FORMAT
>      match at any level below the `.gitignore` level.
>   
>    - Patterns read from exclude sources that are outside the working tree,
> -   such as $GIT_DIR/info/exclude and core.excludesFile, are treated as if
> +   such as $GIT_COMMON_DIR/info/exclude and core.excludesFile, are treated as if
>      they are specified at the root of the working tree, i.e. a leading "/"
>      in such patterns anchors the match at the root of the repository.
>   
> @@ -146,8 +146,8 @@ CONFIGURATION
>   
>   The optional configuration variable `core.excludesFile` indicates a path to a
>   file containing patterns of file names to exclude, similar to
> -`$GIT_DIR/info/exclude`.  Patterns in the exclude file are used in addition to
> -those in `$GIT_DIR/info/exclude`.
> +`$GIT_COMMON_DIR/info/exclude`. Patterns in the exclude file are used in
> +addition to those in `$GIT_COMMON_DIR/info/exclude`.
>   
>   NOTES
>   -----
> diff --git a/dir.c b/dir.c
> index fcb8f6dd2a..33c81c256e 100644
> --- a/dir.c
> +++ b/dir.c
> @@ -2985,7 +2985,7 @@ static struct untracked_cache_dir *validate_untracked_cache(struct dir_struct *d
>   		return NULL;
>   
>   	/*
> -	 * We only support $GIT_DIR/info/exclude and core.excludesfile
> +	 * We only support $GIT_COMMON_DIR/info/exclude and core.excludesfile
>   	 * as the global ignore rule files. Any other additions
>   	 * (e.g. from command line) invalidate the cache. This
>   	 * condition also catches running setup_standard_excludes()
> @@ -3078,7 +3078,7 @@ static struct untracked_cache_dir *validate_untracked_cache(struct dir_struct *d
>   		istate->cache_changed |= UNTRACKED_CHANGED;
>   	}
>   
> -	/* Validate $GIT_DIR/info/exclude and core.excludesfile */
> +	/* Validate $GIT_COMMON_DIR/info/exclude and core.excludesfile */
>   	root = dir->untracked->root;
>   	if (!oideq(&dir->internal.ss_info_exclude.oid,
>   		   &dir->untracked->ss_info_exclude.oid)) {
> diff --git a/dir.h b/dir.h
> index 20d4a078d6..83e0f648a8 100644
> --- a/dir.h
> +++ b/dir.h
> @@ -153,7 +153,7 @@ struct oid_stat {
>    *   - The list of files and directories of the directory in question
>    *   - The $GIT_DIR/index
>    *   - dir_struct flags
> - *   - The content of $GIT_DIR/info/exclude
> + *   - The content of $GIT_COMMON_DIR/info/exclude
>    *   - The content of core.excludesfile
>    *   - The content (or the lack) of .gitignore of all parent directories
>    *     from $GIT_WORK_TREE
> 
> base-commit: 59709faab07346122d819453f4ad6f3ccdaf618e