Skip to main content
This page documents all configuration settings available in LazyWorktree, organised by category.

​
Core Settings

​
worktree_dir
string
default:"~/.local/share/worktrees"
Directory where your worktrees will be created. Supports tilde expansion.

​
Worktree List

​
sort_mode
string
default:"switched"
How worktrees are sorted in the list.Options:
  • switched - Last accessed by you (default)
  • active - Last commit date
  • path - Alphabetical
​
layout
string
default:"default"
Pane arrangement. Toggle at runtime with L.Options:
  • default - Worktrees left, status/log stacked right; notes split left when present
  • top - Worktrees full-width top, notes row below when present, status/log side-by-side bottom
​
auto_refresh
boolean
default:true
Refresh git metadata and working tree status in the background. Set to false to rely on manual refresh with r.
​
refresh_interval
integer
default:10
Background refresh interval in seconds.
​
ci_auto_refresh
boolean
default:false
Periodically refresh CI status for GitHub repositories. When enabled, CI checks are refreshed automatically for open PRs or branches with pending CI jobs. Disabled by default as it uses the GitHub API rate limit (5,000 requests/hour for authenticated users).
​
max_name_length
integer
default:95
Maximum length for worktree names in the table display. Set to 0 to disable truncation.

​
UI & Display

​
theme
string
default:""
TUI theme. Leave empty to auto-detect based on terminal background colour (defaults to rose-pine for dark terminals, dracula-light for light terminals).See Themes for the complete list of built-in themes and custom theme options.
​
icon_set
string
default:"nerd-font-v3"
Icon set for file trees, PR views, and UI indicators.Options:
  • nerd-font-v3 - Nerd Font icons
  • text - Text-only (no icons)
​
search_auto_select
boolean
default:false
Start with the filter focused and automatically select the first match when you press Enter.
​
fuzzy_finder_input
boolean
default:false
Show fuzzy suggestions in input dialogues.
​
palette_mru
boolean
default:true
Enable MRU (Most Recently Used) sorting for command palette.
​
palette_mru_limit
integer
default:5
Number of recent commands to show in command palette.

​
Diff & Pager

​
git_pager
string
default:"delta"
Diff formatter/pager used for rendering diffs. Set to empty string ("") to disable diff formatting and use plain git diff output.Examples: delta, diff-so-fancy, diffnav, lumen
​
git_pager_args
array
default:["--syntax-theme","Dracula"]
Extra arguments passed to git_pager. If you omit this setting and git_pager is delta, LazyWorktree automatically selects a syntax theme matching your UI theme.
​
git_pager_interactive
boolean
default:false
Set to true for interactive diff viewers that need terminal control (e.g., diffnav, tig). Interactive tools cannot be piped through less. When true, only unstaged changes (git diff) are shown.
​
git_pager_command_mode
boolean
default:false
Set to true for command-based diff viewers that run their own git commands (e.g., lumen which accepts lumen diff). When true, LazyWorktree calls <git_pager> diff [args...] directly instead of piping git diff output.
​
pager
string
default:"less --use-color --wordwrap -qcR"
Pager used for show_output custom commands. Defaults to $PAGER environment variable or less if unset.
​
ci_script_pager
string
default:""
Pager for CI check logs (accessed with v key on CI checks). When set, runs interactively with direct terminal control. Falls back to pager if not configured.Example to strip GitHub Actions timestamps:
ci_script_pager: |
  sed -E '
  s/.*[0-9]{4}-[0-9]{2}-[0-9]{2}T([0-9]{2}:[0-9]{2}:[0-9]{2})\.[0-9]+Z[[:space:]]*/\1 /;
  t;
  s/.*UNKNOWN STEP[[:space:]]+//' | \
   tee /tmp/.ci.${LW_CI_JOB_NAME_CLEAN}-${LW_CI_STARTED_AT}.md |
  less --use-color -q --wordwrap -qcR -P 'Press q to exit..'
CI environment variables: LW_CI_JOB_NAME, LW_CI_JOB_NAME_CLEAN, LW_CI_RUN_ID, LW_CI_STARTED_AT
​
max_untracked_diffs
integer
default:10
Maximum number of untracked files to show diffs for. Set to 0 to disable diff display for untracked files.
​
max_diff_chars
integer
default:200000
Maximum characters to read from diff output. Set to 0 to disable truncation.

​
Editor

​
editor
string
default:"nvim"
Editor for opening files from the Status pane (triggered with e key). Defaults to $EDITOR environment variable, then nvim, then vi.

​
Lifecycle Hooks

​
init_commands
array
default:["link_topsymlinks"]
Commands to run after creating a new worktree. Executes when creating worktrees from branches, PRs, issues, or changes. Execution order: global config commands first, then repository-specific commands from .wt files.Special built-in command:
  • link_topsymlinks - Symlinks untracked/ignored files from main worktree root, non-empty editor configs (.vscode, .idea, .cursor, .claude), creates tmp/ directory, runs direnv allow if .envrc exists
Environment variables available: WORKTREE_PATH, WORKTREE_BRANCH, WORKTREE_NAME, MAIN_WORKTREE_PATH, REPO_NAMEExamples:
init_commands:
  - link_topsymlinks
  - cp $MAIN_WORKTREE_PATH/.env $WORKTREE_PATH/.env
  - npm install
​
terminate_commands
array
default:[]
Commands to run before deleting a worktree. Executes when deleting individual worktrees or pruning merged worktrees. Execution order: global config commands first, then repository-specific commands from .wt files.Environment variables available: Same as init_commandsExamples:
terminate_commands:
  - echo "Cleaning up $WORKTREE_NAME"
  - rm -rf $WORKTREE_PATH/tmp/*
​
worktree_notes_path
string
default:""
Optional path to store all worktree notes in a single shared JSON file. Useful when synchronising notes across systems. In this mode, notes are keyed by repo/worktree (relative to worktree_dir), rather than absolute paths.Example: ~/.local/share/lazyworktree/worktree-notes.json

​
Git Operations

​
merge_method
string
default:"rebase"
Merge method for the “Absorb worktree” action and Sync (S) behaviour.Options:
  • rebase - Rebases onto main, then fast-forwards main to the branch (default)
  • merge - Creates a merge commit on main
​
disable_pr
boolean
default:false
Disable all PR/MR fetching and display.

​
Branch Naming

See Branch Naming for detailed information on these settings.
​
issue_branch_name_template
string
default:"issue-{number}-{title}"
Template for issue branch names when creating worktrees from issues.Available placeholders: {number}, {title}, {generated}
​
pr_branch_name_template
string
default:"pr-{number}-{title}"
Template for PR branch and worktree names when creating from pull requests.Available placeholders: {number}, {title}, {generated}, {pr_author}
​
branch_name_script
string
default:""
Script to generate branch name suggestions when creating worktrees from changes, issues, or PRs.For issues/PRs: outputs a title used in the {generated} placeholderFor diffs: outputs a complete branch nameThe script receives content on stdin and has access to environment variables: LAZYWORKTREE_TYPE, LAZYWORKTREE_NUMBER, LAZYWORKTREE_TEMPLATE, LAZYWORKTREE_SUGGESTED_NAME
​
worktree_note_script
string
default:""
Script to generate an initial worktree note when creating from a PR/MR or issue. The script receives title + body on stdin.Environment variables: LAZYWORKTREE_TYPE, LAZYWORKTREE_NUMBER, LAZYWORKTREE_TITLE, LAZYWORKTREE_URL

​
Session Management

​
session_prefix
string
default:"wt-"
Prefix for tmux/zellij session names. Command palette filters sessions by this prefix.

​
Security

​
trust_mode
string
default:"tofu"
Security setting for executing commands from .wt files.Options:
  • tofu - Trust On First Use - prompts you the first time or when commands change (default)
  • never - Skips all commands from .wt files
  • always - Executes without prompting (use with caution)
See .wt Files and TOFU Security for more details.
​
debug_log
string
default:""
Debug log file path for troubleshooting. When set, LazyWorktree writes debug information to this file. Leave commented out unless diagnosing issues.Example: /tmp/lazyworktree-debug.log

Build docs developers (and LLMs) love

Get started for freeTalk to us