[RFC] worktree: add lifecycle hooks

[RFC] worktree: add lifecycle hooks

[Maciej Ciemborowicz]

Hello,

I'd like to discuss adding native hooks for worktree lifecycle events.

Git currently invokes `post-checkout` after `git worktree add` when a
checkout is performed. This makes it possible to detect some worktree
creation cases indirectly. There does not appear to be a native hook for
other worktree lifecycle operations such as:

    git worktree add
    git worktree remove
    git worktree move
    git worktree lock
    git worktree unlock
    git worktree prune

As a result, tools which want to react to these operations have to wrap
`git worktree` or compare the worktree state before and after a command.
They cannot observe an invocation which bypasses their wrapper.

One concrete use case is git-hooks-ext, which provides higher-level events
for Git operations. It currently has to implement worktree events by
wrapping `git worktree` and comparing the output of `git worktree list
--porcelain` before and after the command.

Would it make sense for Git to expose worktree lifecycle events directly?

One possibility would be separate post-operation hooks such as:

    post-worktree-add
    post-worktree-remove
    post-worktree-move
    post-worktree-lock
    post-worktree-unlock

Another possibility would be a single hook, similar in spirit to
`reference-transaction`, which reports worktree lifecycle changes. An
illustrative payload could look like:

    add    <path>
    remove <path>
    move   <old-path> <new-path>
    lock   <path>
    unlock <path>
    prune  <path>

A single hook may be useful for operations such as `git worktree prune`,
where one command can remove multiple administrative entries. It could
also leave room for `git worktree repair`, although I am unsure whether
repair belongs to the same interface.

For the use case I have in mind, these hooks would only need to notify
observers after a successful operation. They would not need to veto the
operation.

Before attempting an implementation, I'd like to know whether this would
fit Git's hook model, and whether a single lifecycle hook or individual
operation hooks would be preferable. I would also appreciate guidance on
whether a stable worktree identifier should be exposed in addition to the
path.

Thanks,
Maciej Ciemborowicz

Re: [RFC] worktree: add lifecycle hooks

[Kristoffer Haugsbakk]

On Sun, Sep 20, 2026, at 19:33, Maciej Ciemborowicz wrote:
> Hello,
>
> I'd like to discuss adding native hooks for worktree lifecycle events.
>
> Git currently invokes `post-checkout` after `git worktree add` when a
> checkout is performed. This makes it possible to detect some worktree
> creation cases indirectly. There does not appear to be a native hook for
> other worktree lifecycle operations such as:
>
>     git worktree add
>     git worktree remove
>     git worktree move
>     git worktree lock
>     git worktree unlock
>     git worktree prune
>[snip]

See https://lore.kernel.org/git/7c8b4673-37ac-45fa-ad8c-a1dc09afe5fe@mtasv.net/

Re: [RFC] worktree: add lifecycle hooks

[Michał Papis]

The important piece for your use case is the pre-worktree-remove hook,
not just post-operation hooks.

Post-hooks fire after the worktree is already gone. That's fine when a
tool's state lives entirely inside the worktree. It breaks when the
worktree points at state outside it — a docker container, a database,
sockets, volumes. Then the worktree itself is the registry: its config
is the only mapping from worktree to external resources, and
pre-remove is the only moment that mapping is still readable. After
removal you're guessing — hunting the disk for orphans, diffing
against remaining worktrees, turning deterministic teardown into
stale-data detection.

Real example: with AI-generated worktrees (one per task, created and
discarded faster than a human types), I was exhausting ~200GB of disk
every week and ended up writing cleanup scripts to reverse-engineer,
from what was left on disk, which containers and databases belonged to
deleted worktrees. A pre-remove hook runs the same teardown with the
config still present.

This is not about vetoing removal — pre-remove needs no power to
countermand anything. It's about doing cleanup with full information
instead of reconstructing it afterward.

One limit, which is why post hooks still matter: pre-remove only
applies to git worktree remove. For manual deletion + git worktree
prune, the tree is already gone, so pre-remove can't see it. The two
are complementary.

Cheers / Pozdrawiam,
Michal

--
Michal Papis
phone. +48 603 751 266