FAQ¶

Use this page when: you have a quick question about LazyWorktree's behaviour or capabilities.

Do I need to use shell integration?¶

No. Shell helpers are entirely optional. LazyWorktree works as a standalone TUI without any shell integration.

Shell integration makes cd-to-selected-worktree smoother by exporting the selected path back to your calling shell. Without it, you can still navigate worktrees, but switching your shell's working directory requires a manual cd after exiting. See Shell Integration for setup instructions.

Can I keep one notes file across repositories?¶

Yes. Set worktree_notes_path to store all worktree notes in a single JSON file:

worktree_notes_path: ".lazyworktree/notes.json"

When this is set, note keys are stored relative to worktree_dir rather than as absolute paths, making the file portable across machines. Commit the JSON file to share notes with your team.

Where are notes stored by default?¶

Without worktree_notes_path, notes are stored in the repository's local git config (git config --local). This means they are specific to each clone and are not shared or synchronised automatically.

Why is my PR branch name different after create-from-PR?¶

When creating a worktree from a PR, LazyWorktree uses the configured pr_branch_name_template to generate the branch name. If branch_name_script is configured and the template includes {generated}, the AI-generated name may differ from the original PR branch. If the script fails or times out, {generated} falls back to {title}.

To preserve the original PR branch name exactly, use a template without {generated}:

pr_branch_name_template: "pr-{number}-{title}"

Why are `.wt` commands not running?¶

Check your trust_mode configuration:

tofu (default): prompts on first use and when the .wt file changes. If you selected Block, remove the entry from ~/.local/share/lazyworktree/trusted.json to be prompted again.
never: blocks all .wt execution. Change to tofu or always to enable hooks.
always: runs without prompting.

Also verify the .wt file is in the repository root, not a subdirectory. See the Diagnostic Guide for further steps.

Can I use custom command keys from CLI?¶

Yes. Use lazyworktree exec with the --key flag:

lazyworktree exec --key=e              # Run custom command bound to 'e'
lazyworktree exec --key=e --workspace  # Run in a specific workspace

This executes the custom command as if you had pressed the key in the TUI, but without launching the interface.

Why does `new-tab` not work from CLI `exec`?¶

The new-tab command type is intentionally unsupported in CLI mode. It requires a running multiplexer session (tmux or zellij) to create a new tab, which is only available when LazyWorktree is running inside the TUI. Use shell or command types for CLI-compatible commands.

How do I change the worktree sort order?¶

Set sort_mode in your configuration:

sort_mode: switched   # Most recently switched-to first (default)
# sort_mode: active   # Worktrees with uncommitted changes first
# sort_mode: path     # Alphabetical by path

How do I use a different diff viewer?¶

Configure the pager setting to use your preferred diff tool:

pager: "delta"                    # delta with default settings
# pager: "diff-so-fancy | less"  # diff-so-fancy piped to less

For interactive pagers, you may also need:

git_pager_interactive: true

See Diff, Pager, and Editor and Integration Caveats for tested combinations.

Can I disable PR/MR fetching entirely?¶

Yes. Set disable_pr to skip all GitHub/GitLab API calls:

disable_pr: true

This is useful for repositories where you do not use PRs, or to avoid API rate limits on large organisations.

Where should I start debugging visual issues?¶

Start with Fonts and Rendering to check your font and terminal colour support. If the issue is theme-related, try switching to a different built-in theme. For all other issues, follow the Diagnostic Guide.