Read files from the worktree git dir instead of the shared repository

Inside a linked git worktree, GrumPHP listed and diffed files against the main
repository's branch instead of the worktree's own. A task could then fail on a
file that exists on main but not in the worktree:

    yamllint: SplFileInfo::openFile(config/services/commands.yaml):
              Failed to open stream: No such file or directory

A worktree's .git is a file pointing at <main>/.git/worktrees/<id>, and that
directory's commondir points back to the shared <main>/.git. GrumPHP collapsed
the worktree straight to that shared directory and used it for everything,
including the git client that lists files. So "git --git-dir=<main>/.git
ls-files" returned main's index. The gitonomy client passes --git-dir on the
command line, which overrides GIT_DIR, so correcting the environment around
GrumPHP could not reach it.

Collapsing to the shared directory is correct for hooks: a worktree runs the
main repository's hooks. So the two concerns are now separate. Hooks still
resolve to the shared .git; the git client that lists files and reads diffs
points at the worktree's own git dir. A normal checkout and a submodule resolve
as before.

GRUMPHP_GIT_REPOSITORY_DIR still overrides the resolved directory and now drives
both the hooks dir and the file-listing dir, which matches how it behaved before
the split.

Author: veewee

doc/installation/exotic.md

@@ -94,6 +94,8 @@ The path to the root directory of your git project.
 The path to the directory in which git stores it objects etc.
 Most of the time this is the .git folder.
 When using GIT submodules, this is the location of the submodule .git folder.
+Inside a linked git worktree, this points at the shared repository root, since worktrees run the hooks
+of the main repository. File listing and diffs still use the worktree's own branch.
 
 **GRUMPHP_COMPOSER_DIR**
 

src/Configuration/GuessedPaths.php

@@ -43,14 +43,20 @@ class GuessedPaths
      */
     private $configFile;
 
+    /**
+     * @var string
+     */
+    private $gitWorktreeDir;
+
     public function __construct(
         string $gitWorkingDir,
         string $gitRepositoryDir,
         string $workingDir,
         string $projectDir,
         string $binDir,
         ComposerFile $composerFile,
-        string $configFile
+        string $configFile,
+        ?string $gitWorktreeDir = null
     ) {
         $this->gitWorkingDir = $gitWorkingDir;
         $this->gitRepositoryDir = $gitRepositoryDir;
@@ -59,6 +65,7 @@ public function __construct(
         $this->binDir = $binDir;
         $this->composerFile = $composerFile;
         $this->configFile = $configFile;
+        $this->gitWorktreeDir = $gitWorktreeDir ?? $gitRepositoryDir;
     }
 
     public function getGitWorkingDir(): string
@@ -71,6 +78,11 @@ public function getGitRepositoryDir(): string
         return $this->gitRepositoryDir;
     }
 
+    public function getGitWorktreeDir(): string
+    {
+        return $this->gitWorktreeDir;
+    }
+
     public function getWorkingDir(): string
     {
         return $this->workingDir;

src/Locator/EnrichedGuessedPathsFromDotEnvLocator.php

@@ -37,6 +37,10 @@ public function locate(GuessedPaths $guessedPaths): GuessedPaths
             (string) ($_SERVER['GRUMPHP_GIT_REPOSITORY_DIR'] ?? $guessedPaths->getGitRepositoryDir()),
             $workingDir
         );
+        $gitWorktreeDir = $this->filesystem->makePathAbsolute(
+            (string) ($_SERVER['GRUMPHP_GIT_REPOSITORY_DIR'] ?? $guessedPaths->getGitWorktreeDir()),
+            $workingDir
+        );
         $binDir = $this->filesystem->makePathAbsolute(
             (string) ($_SERVER['GRUMPHP_BIN_DIR'] ?? $guessedPaths->getBinDir()),
             $workingDir
@@ -49,7 +53,8 @@ public function locate(GuessedPaths $guessedPaths): GuessedPaths
             $projectDir,
             $binDir,
             $guessedPaths->getComposerFile(),
-            $guessedPaths->getConfigFile()
+            $guessedPaths->getConfigFile(),
+            $gitWorktreeDir
         );
     }
 }

src/Locator/GitRepositoryDirLocator.php

@@ -20,9 +20,27 @@ public function __construct(Filesystem $filesystem)
 
     /**
      * Resolves the path to the git repository directory (aka as .git).
-     * For submodules, it parses the .git file and resolves to the .git/modules/[submodules] directory
+     * For submodules, it parses the .git file and resolves to the .git/modules/[submodules] directory.
+     * For worktrees, it resolves to the common repository root, since worktrees share the main
+     * repository's hooks. Use locateWorktreeGitDir() when the worktree's own git dir is required.
      */
     public function locate(string $gitDir): string
+    {
+        return $this->resolveGitDir($gitDir, true);
+    }
+
+    /**
+     * Resolves the git directory used to read files and diffs.
+     * For worktrees this returns the worktree's own git dir (.git/worktrees/[id]) instead of collapsing
+     * to the common repository root, so file listing and diffs reflect the worktree's branch.
+     * For submodules and normal checkouts this is identical to locate().
+     */
+    public function locateWorktreeGitDir(string $gitDir): string
+    {
+        return $this->resolveGitDir($gitDir, false);
+    }
+
+    private function resolveGitDir(string $gitDir, bool $collapseWorktreeToRoot): string
     {
         if (!$this->filesystem->isFile($gitDir)) {
             return $gitDir;
@@ -36,7 +54,9 @@ public function locate(string $gitDir): string
         $gitRepositoryDir = $matches[1];
 
         if ($this->isWorktree($gitRepositoryDir)) {
-            return $this->locateWorktreeRoot($gitRepositoryDir);
+            return $collapseWorktreeToRoot
+                ? $this->locateWorktreeRoot($gitRepositoryDir)
+                : $gitRepositoryDir;
         }
 
         return $this->filesystem->buildPath(

src/Locator/GitRepositoryLocator.php

@@ -22,7 +22,7 @@ public function __construct(Paths $paths)
     public function locate(array $options): Repository
     {
         return new Repository(
-            $this->paths->getGitRepositoryDir(),
+            $this->paths->getGitWorktreeDir(),
             array_merge(
                 [
                     'working_dir' => $this->paths->getGitWorkingDir(),

src/Locator/GuessedPathsLocator.php

@@ -56,6 +56,12 @@ public function locate(?string $cliConfigFile): GuessedPaths
             )),
             $workingDir
         );
+        $gitWorktreeDir = $this->filesystem->makePathAbsolute(
+            (string) ($_SERVER['GRUMPHP_GIT_REPOSITORY_DIR'] ?? $this->gitRepositoryDirLocator->locateWorktreeGitDir(
+                $this->filesystem->buildPath($gitWorkingDir, '.git')
+            )),
+            $workingDir
+        );
 
         $composerFilePathname = $this->filesystem->guessFile(
             [
@@ -125,7 +131,8 @@ public function locate(?string $cliConfigFile): GuessedPaths
             $projectDir,
             $binDir,
             $composerFile,
-            $defaultConfigFile
+            $defaultConfigFile,
+            $gitWorktreeDir
         );
     }
 

src/Util/Paths.php

@@ -69,6 +69,15 @@ public function getGitRepositoryDir(): string
         return $this->guessedPaths->getGitRepositoryDir();
     }
 
+    /**
+     * The git dir to read files and diffs from. Inside a linked worktree this is the worktree's own
+     * git dir; for normal checkouts and submodules it equals getGitRepositoryDir().
+     */
+    public function getGitWorktreeDir(): string
+    {
+        return $this->guessedPaths->getGitWorktreeDir();
+    }
+
     public function getBinDir(): string
     {
         return $this->guessedPaths->getBinDir();

test/E2E/AbstractE2ETestCase.php

@@ -87,6 +87,25 @@ protected function initializeGitSubModule(string $gitPath, string $submodulePath
         return $this->filesystem->buildPath($gitPath, basename($submodulePath));
     }
 
+    protected function addGitWorktree(string $fromGitPath, string $worktreeName, string $branch): string
+    {
+        $this->changeGitPermissions();
+        $worktreePath = $this->relativeRootPath($worktreeName);
+        $this->runCommand('add git worktree', new Process(
+            [$this->executableFinder->find('git'), 'worktree', 'add', '-b', $branch, $worktreePath],
+            $fromGitPath
+        ));
+
+        return $worktreePath;
+    }
+
+    protected function commitAllWithoutHook(string $gitPath)
+    {
+        $git = $this->executableFinder->find('git');
+        $this->gitAddPath($gitPath);
+        $this->runCommand('commit without hook', new Process([$git, 'commit', '--no-verify', '-mtest'], $gitPath));
+    }
+
     protected function appendToGitignore(string $gitPath, array $paths = ['vendor'])
     {
         $gitignore = $this->filesystem->buildPath($gitPath, '.gitignore');

test/E2E/SpecialGitStructuresTest.php

@@ -29,6 +29,36 @@ function it_runs_inside_a_submodule()
         $this->runGrumphp($submoduleInMain);
     }
 
+    #[Test]
+    function it_runs_inside_a_worktree()
+    {
+        $main = $this->mkdir('main');
+
+        $this->initializeGit($main);
+        $this->appendToGitignore($main);
+        $this->initializeComposer($main);
+        $grumphpFile = $this->initializeGrumphpConfig($main);
+        $this->installComposer($main);
+        $this->ensureHooksExist($main);
+
+        // A file that lives on the main branch but not on the worktree's branch:
+        $this->dumpFile($this->filesystem->buildPath($main, 'only-on-main.txt'), 'main');
+        $this->enableValidatePathsTask($grumphpFile, $main);
+        $this->commitAll($main);
+
+        // A linked worktree on a diverging branch that drops the main-only file:
+        $worktree = $this->addGitWorktree($main, 'worktree', 'feature');
+        $this->filesystem->remove($this->filesystem->buildPath($worktree, 'only-on-main.txt'));
+        $this->commitAllWithoutHook($worktree);
+
+        $this->installComposer($worktree);
+        $worktreeGrumphpFile = $this->initializeGrumphpConfig($worktree);
+        $this->enableValidatePathsTask($worktreeGrumphpFile, $worktree);
+
+        // GrumPHP must list the worktree's branch, so only-on-main.txt stays out of the file list:
+        $this->runGrumphp($worktree);
+    }
+
     #[Test]
     function it_handles_partial_commits()
     {

test/Unit/Locator/EnrichedGuessedPathsFromDotEnvLocatorTest.php

@@ -83,6 +83,26 @@ function (Filesystem $filesystem, string $workspace) use ($configure) {
         ];
 
 
+        yield 'keep-distinct-worktree-dir' => [
+            function (Filesystem $filesystem, string $workspace) use ($configure) {
+                \Closure::bind($configure, $this)($workspace);
+            },
+            $inputWithWorktree = function (string $workspace) {
+                return new GuessedPaths(
+                    $workspace,
+                    $this->path('.git'),
+                    $workspace,
+                    $workspace,
+                    $this->path('vendor/bin'),
+                    new ComposerFile($this->path('composer.json'), []),
+                    $this->path('grumphp.yml'),
+                    $this->path('.git/worktrees/wt1')
+                );
+            },
+            $inputWithWorktree
+        ];
+
+
         yield 'overwritten-config' => [
             function (Filesystem $filesystem, string $workspace) use ($configure) {
                 \Closure::bind($configure, $this)($workspace);