Custom Initialisation and Termination¶

Create a .wt file in your repository to run commands when creating or removing worktrees. Format inspired by wt.

Refer to this page when: you want to automate setup or cleanup tasks when worktrees are created or deleted.

`.wt` File Format¶

Place a .wt file in your repository root. It uses YAML with two keys: init_commands (run after worktree creation) and terminate_commands (run before worktree removal).

Example¶

init_commands:
    - link_topsymlinks
    - cp $MAIN_WORKTREE_PATH/.env $WORKTREE_PATH/.env
    - npm install
    - direnv allow $WORKTREE_PATH
    - docker compose -f $WORKTREE_PATH/docker-compose.yml up -d

terminate_commands:
    - docker compose -f $WORKTREE_PATH/docker-compose.yml down
    - echo "Cleaned up $WORKTREE_NAME"

Environment Variables¶

The following variables are available to all init and terminate commands:

Variable	Description	Example
`WORKTREE_BRANCH`	Branch checked out in the new worktree	`feature/auth`
`MAIN_WORKTREE_PATH`	Absolute path to the main (bare) worktree	`/home/user/project`
`WORKTREE_PATH`	Absolute path to the new worktree	`/home/user/project-worktrees/feature-auth`
`WORKTREE_NAME`	Short name of the worktree	`feature-auth`
`REPO_NAME`	Repository key, usually `owner/repo`	`acme/project`
`REPO_OWNER`	Repository owner when available	`acme`
`REPO_REPONAME`	Repository name without the owner	`project`
`LAZYWORKTREE_TYPE`	Source context type when known	`pr`
`LAZYWORKTREE_NUMBER`	PR/MR or issue number when known	`42`
`LAZYWORKTREE_TITLE`	PR/MR or issue title when known	`Add auth`
`LAZYWORKTREE_URL`	PR/MR or issue URL when known	`https://github.com/acme/project/pull/42`
`LAZYWORKTREE_DESCRIPTION`	PR/MR or issue body when known	`Adds authentication`

Contextual LAZYWORKTREE_* values are empty when no PR/MR, issue, or diff source context is known.

Execution Order¶

Commands execute in the order listed. If you also have global init_commands or terminate_commands in your LazyWorktree configuration file, those run before the repository .wt commands. This allows global setup (e.g., shell environment) to complete before project-specific commands.

If a command exits with a non-zero code, the remaining commands still run.

Special Commands¶

`link_topsymlinks`¶

A built-in command (not a shell command) that automates common worktree setup tasks:

Symlink untracked files and ignored files at the repository root from the main worktree into the new worktree. This keeps local configuration, overrides, and build artefacts available without tracking them.
Symlink editor configuration directories such as .vscode, .idea, .cursor, and .claude/settings.local.json.
Create a tmp/ directory in the new worktree.
Run direnv allow if a .envrc file exists in the main worktree.

Security: Trust on First Use (TOFU)¶

Since .wt files execute arbitrary commands, LazyWorktree uses a TOFU model to protect against unintended execution.

How it works¶

First encounter: LazyWorktree hashes the .wt file and prompts you to Trust, Block, or Cancel. When the prompt appears for a new worktree, the worktree already exists, so the last button reads Cancel Setup: it keeps the worktree and skips its commands.
Subsequent runs: the hash is compared against the stored value. If it matches, commands run without prompting
File modified: if the .wt file has changed since you last trusted it (even whitespace changes), the hash will no longer match and you will be prompted again

Trust decisions are stored in ~/.local/share/lazyworktree/trusted.json.

Trust modes¶

Mode	Behaviour
`tofu`	Prompt on first use and when the file changes (default)
`never`	Skip all `.wt` commands without prompting
`always`	Always execute without prompting (use with caution)

Configure in your LazyWorktree config:

trust_mode: tofu

Re-prompting triggers¶

You will be prompted to re-evaluate trust when:

The .wt file content changes (hash mismatch)
The trusted.json file is deleted or the entry is removed
You switch from never or always back to tofu mode