<div id="readability-page-1" class="page"><div>
      
        <header>
          
          

  <p>
    

    

    
      
      

      <span>
        
        
          1 minute read
        
      </span>
    
  </p>


        </header>
      

      <section itemprop="text">
        
        <h2 id="environment">Environment</h2>

<ul>
  <li>lefthook v2.1.6</li>
  <li>git v2.54.0</li>
</ul>

<h2 id="background">Background</h2>

<ul>
  <li>git executes files with reserved names, such as <code>pre-commit</code>, located under <code>.git/hooks</code> at specific points in its workflow. This is a built-in feature of git.</li>
  <li>Initially, the directory only contains example files suffixed with <code>.sample</code>, so no hooks run. Once you create an executable file with the exact reserved name, that git hook will run from then on.</li>
  <li><code>lefthook install</code> generates a shell script that says “find the lefthook binary and run it,” and places it at <code>.git/hooks/pre-*</code>. At this point, the path to the lefthook binary is hardcoded into the script.</li>
  <li>Every time a git hook fires, the lefthook binary reads the jobs described in the <code>lefthook.yml</code> DSL and executes them. This is why changes to jobs in the yml take effect immediately, without re-running <code>lefthook install</code>.</li>
</ul>

<h2 id="how-lefthook-runs-step-by-step">How lefthook runs, step by step</h2>

<ol>
  <li>A git command is executed</li>
  <li>git runs the hook script in <code>.git/hooks</code></li>
  <li>The git hook script runs the lefthook binary</li>
  <li>The lefthook binary executes the jobs registered in <code>lefthook.yml</code></li>
</ol>

<h2 id="why-this-matters">Why this matters</h2>

<p>Creating a new <code>git worktree</code> does not create a new <code>.git/hooks</code>. A git repository has exactly one <code>.git/hooks</code>, shared across all worktrees.</p>

<p>As long as you run <code>lefthook install</code> only in the primary worktree, everything is fine.</p>

<p><strong>But if you run <code>lefthook install</code> in a newly created linked worktree, the lefthook binary path registered in <code>.git/hooks</code> gets hardcoded to the binary inside that linked worktree.</strong></p>

<p>While the linked worktree is alive, nothing goes wrong. But when you delete the linked worktree, the lefthook binary is deleted along with it.</p>

<p>After that, git hooks still fire without raising any error. All you get is a message: “Can’t find lefthook in PATH”. The lefthook binary was removed together with the linked worktree. If you put blind faith in lefthook, you may end up feeling betrayed.</p>

<p>20260604</p>

        
      </section>

      

      


      
  


    </div></div>

Never test

Environment
lefthook v2.1.6
git v2.54.0
Background
git executes files with reserved names, such as pre-commit, located under .git/hooks at specific points in its workflow. This is a built-in feature of git.
Initially, the directory only contains example files suffixed with .sample, so no hooks run. Once you create an executable file with the exact reserved name, that git hook will run from then on.
lefthook install generates a shell script that says “find the lefthook binary and run it,” and places it at .git/hooks/pre-*. At this point, the path to the lefthook binary is hardcoded into the script.
Every time a git hook fires, the lefthook binary reads the jobs described in the lefthook.yml DSL and executes them. This is why changes to jobs in the yml take effect immediately, without re-running lefthook install.
How lefthook runs, step by step
A git command is executed
git runs the hook script in .git/hooks
The git hook script runs the lefthook binary
The lefthook binary executes the jobs registered in lefthook.yml
Why this matters
Creating a new git worktree does not create a new .git/hooks. A git repository has exactly one .git/hooks, shared across all worktrees.
As long as you run lefthook install only in the primary worktree, everything is fine.
But if you run lefthook install in a newly created linked worktree, the lefthook binary path registered in .git/hooks gets hardcoded to the binary inside that linked worktree.
While the linked worktree is alive, nothing goes wrong. But when you delete the linked worktree, the lefthook binary is deleted along with it.
After that, git hooks still fire without raising any error. All you get is a message: “Can’t find lefthook in PATH”. The lefthook binary was removed together with the linked worktree. If you put blind faith in lefthook, you may end up feeling betrayed.
20260604

How lefthook works — why you should never run install in a linked worktree

댓글