Subject: [PATCH v2] ignore: note info/exclude lives in GIT_COMMON_DIR, not GIT_DIR

From: "D. Ben Knoble" <[email-masked]>
Date: Fri, 8 May 2026 10:14:14 -0400

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
to say so.

Signed-off-by: D. Ben Knoble <[email-masked]>
---

Notes (benknoble/commits):
    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: <e3ee0a11b[email-masked]>
    
    v1 notes:
    
    Discussed briefly at https://lore.kernel.org/git/[email-masked]/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/gitignore.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/gitignore.adoc b/Documentation/gitignore.adoc
index a3d24e5c34..c423b650de 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`.

base-commit: 4f69b47b940100b02630f745a52f9d9850f122b2
-- 
2.54.0.564.ge3ee0a11b5.dirty