lazyworktree.1

.TH LAZYWORKTREE 1 "January 2026" "lazyworktree" "User Commands"
.SH NAME
lazyworktree \- A TUI tool to manage git worktrees
.
.SH SYNOPSIS
.B lazyworktree
[\fIOPTIONS\fR]
.br
.B lazyworktree wt\-create
[\-\-from\-branch \fIBRANCH\fR] [\-\-name \fINAME\fR] | [\-\-from\-pr \fINUMBER\fR]
| [\-\-from\-pr\-interactive|\-P] | [\-\-from\-issue \fINUMBER\fR]
| [\-\-from\-issue\-interactive|\-I]
[\-\-query|\-q \fISTRING\fR]
[\-\-with\-change] [\-\-silent]
.br
.B lazyworktree wt\-rename
[\-\-silent] [\fIWORKTREE\fR] [\fINEW\-NAME\fR]
.br
.B lazyworktree wt\-delete
[\-\-no\-branch] [\-\-silent]
.
.SH DESCRIPTION
lazyworktree is a BubbleTea-based Terminal User Interface (TUI) designed for efficient Git worktree management. It enables you to visualise the repository's status, oversee branches, and navigate between worktrees with ease.
.
.SH FEATURES
.IP \(bu 2
Worktree Management: Create, rename, delete, absorb, and prune merged worktrees
.IP \(bu 2
Cherry-pick Commits: Copy commits from one worktree to another via an interactive worktree picker
.IP \(bu 2
Commit Log Details: Commit pane shows author initials alongside commit subjects
.IP \(bu 2
Base Selection: Select a base branch or commit from a list, or enter a reference when creating a worktree
.IP \(bu 2
Forge Integration: Fetch and display associated Pull Request (GitHub) or Merge Request (GitLab) status and CI checks with icons from the selected icon set when enabled
.IP \(bu 2
Create from PR/MR: Establish worktrees directly from open pull or merge requests via the create worktree menu (c)
.IP \(bu 2
Create from current branch: Start a worktree from the branch you currently occupy; the branch name prompt offers a friendly random suggestion that you may override, and the checkbox shown during naming optionally carries over uncommitted work.
.IP \(bu 2
Checkout existing branch: When selecting an existing local branch, choose to associate a worktree with it directly (no new branch created) or create a new branch based on it.
.IP \(bu 2
Create from Issue: Establish worktrees from GitHub/GitLab issues with automatic branch name generation
.IP \(bu 2
Status at a Glance: View dirty state, ahead/behind counts, and divergence from main
.IP \(bu 2
Tmux Integration: Create and manage tmux sessions per worktree with multi-window support
.IP \(bu 2
Zellij Integration: Create and manage zellij sessions per worktree with multi-tab support
.IP \(bu 2
Diff Viewer: View diff with optional delta support
.IP \(bu 2
Repo Automation: \fB.wt\fR init/terminate commands with TOFU security
.IP \(bu 2
LazyGit Integration: Launch lazygit directly for the currently selected worktree
.IP \(bu 2
Mouse Support: Click to focus panes, select items, and scroll with the mouse wheel
.
.SH OPTIONS
.TP
.B \-\-worktree\-dir \fIDIR\fR
Override the default worktree root directory.
.br
Default: ~/.local/share/worktrees
.
.TP
.B \-\-theme \fINAME\fR
Select a UI theme. Available themes: dracula, dracula-light, narna, clean-light, catppuccin-latte, rose-pine-dawn, one-light, everforest-light, everforest-dark, solarized-dark, solarized-light, gruvbox-dark, gruvbox-light, nord, monokai, catppuccin-mocha, modern, tokyo-night, one-dark, rose-pine, ayu-mirage, kanagawa.
.br
If unspecified, lazyworktree attempts to auto-detect the theme based on the terminal's background colour (defaulting to rose-pine for dark or dracula-light for light).
.
.TP
.B \-\-show\-syntax\-themes
Display the default delta syntax-theme values for each UI theme.
.
.TP
.B \-\-search\-auto\-select
Start with filter focused and select first match on Enter.
.
.TP
.B \-\-output\-selection \fIFILE\fR
Write the selected worktree path to FILE on exit (for shell integration).
.
.TP
.B \-\-debug\-log \fIPATH\fR
Path to debug log file for troubleshooting.
.
.TP
.B \-\-version
Print version information and exit.
.
.TP
.B \-\-completion \fISHELL\fR
Generate shell completion script (bash, zsh, fish).
.
.TP
.B \-\-config\-file \fIFILE\fR
Path to configuration file, overriding the default XDG config directory location.
.
.TP
.B \-\-config \fIKEY=VALUE\fR
Override config values from the command line (repeatable).
.br
Format: \fB--config=lw.key=value\fR
.br
Supported keys: \fBtheme\fR, \fBworktree_dir\fR, \fBsort_mode\fR, \fBauto_refresh\fR, \fBdisable_pr\fR, \fBsearch_auto_select\fR, \fBfuzzy_finder_input\fR, \fBicon_set\fR, \fBpalette_mru\fR, \fBpalette_mru_limit\fR, \fBgit_pager\fR, \fBgit_pager_args\fR, \fBgit_pager_interactive\fR, \fBgit_pager_command_mode\fR, \fBpager\fR, \fBeditor\fR, \fBmax_untracked_diffs\fR, \fBmax_diff_chars\fR, \fBrefresh_interval_seconds\fR, \fBtrust_mode\fR, \fBmerge_method\fR, \fBbranch_name_script\fR, \fBworktree_note_script\fR, \fBworktree_notes_path\fR, \fBissue_branch_name_template\fR, \fBpr_branch_name_template\fR, \fBsession_prefix\fR, \fBinit_commands\fR, \fBterminate_commands\fR.
.br
Examples: \fB--config=lw.theme=nord\fR, \fB--config=lw.sort_mode=active\fR
.br
This has the highest precedence and overrides all other configuration sources.
.
.SH SUBCOMMANDS
.SS create
Create a new worktree without launching the TUI.
.
.PP
.B Options:
.TP
.B \fINAME\fR
Optional positional argument for the worktree and branch name. If not provided, the name is automatically generated by sanitising the source branch name (lowercase, alphanumeric characters and hyphens only). Can be used with or without \-\-from\-branch.
.
.TP
.B \-\-from\-branch \fIBRANCH\fR
Create worktree from the specified branch. If not provided, uses the current branch from the working directory. If a name is provided as a positional argument, uses that as the worktree and branch name; otherwise, generates a sanitised name from the source branch.
.
.TP
.B \-\-from\-pr \fINUMBER\fR
Create worktree from PR number. Fetches the specified PR and generates the worktree name from \fBpr_branch_name_template\fR (with optional \fBbranch_name_script\fR). Local branch naming is conditional: if the authenticated requester matches the PR author, the PR branch name is kept; otherwise the generated name is used. If requester identity cannot be resolved, lazyworktree falls back to the PR branch name.
.
.TP
.B \-\-from\-issue \fINUMBER\fR
Create worktree from issue number. Fetches the specified issue and creates a worktree with a sanitised branch name derived from the \fBissue_branch_name_template\fR (default: issue-{number}-{title}, e.g., issue-42-fix-memory-leak). Uses the current branch as the base; combine with \-\-from\-branch to specify a different base.
.
.TP
.B \-\-from\-issue\-interactive\fR, \fB\-I\fR
Interactively select an open issue to create a worktree from. When \fBfzf\fR is installed, presents a searchable list with issue body preview; otherwise displays a numbered list for selection. Shares the same constraints as \-\-from\-issue (mutually exclusive with \-\-from\-pr, cannot combine with \-\-with\-change or a positional name). Combine with \-\-from\-branch to specify a base branch.
.
.TP
.B \-\-from\-pr\-interactive\fR, \fB\-P\fR
Interactively select an open pull request to create a worktree from. When \fBfzf\fR is installed, presents a searchable list with PR metadata preview (author, branches, draft status, CI); otherwise displays a numbered list for selection. Mutually exclusive with \-\-from\-pr, \-\-from\-issue, \-\-from\-issue\-interactive, and \-\-from\-branch. Cannot combine with \-\-with\-change or a positional name.
.
.TP
.B \-\-query \fISTRING\fR\fR, \fB\-q \fISTRING\fR
Pre\-filter the interactive selection list. Requires \-\-from\-pr\-interactive or \-\-from\-issue\-interactive. When \fBfzf\fR is available, the search box is pre\-filled with the given string; otherwise the numbered list is filtered to items whose display line contains the string (case\-insensitive substring match).
.
.TP
.B \-\-generate
Generate the worktree name automatically from the current branch. Cannot be used with a positional name argument or \-\-from\-pr.
.
.TP
.B \-\-with\-change
Carry over uncommitted changes to the new worktree. Works with current branch or \-\-from\-branch. Cannot be used with \-\-from\-pr or \-\-from\-issue. Stashes changes from current worktree, creates new worktree, and applies the stash.
.
.TP
.B \-\-no\-workspace
Skip worktree creation entirely. Instead, creates a local branch and switches to it in the current working directory. Must be used with \-\-from\-pr, \-\-from\-pr\-interactive, \-\-from\-issue, or \-\-from\-issue\-interactive. Cannot be combined with \-\-with\-change, \-\-generate, or a positional name argument. Outputs the branch name rather than a worktree path.
.
.TP
.B \-\-silent
Suppress all progress messages to stderr. Only the worktree path is written to stdout unless \-\-output\-selection is used. Useful for scripting and automation.
.TP
.B \-\-exec \fICOMMAND\fR
Run a post\-create command through the current shell environment. The command runs in the created worktree directory, or in the current directory when used with \-\-no\-workspace. Shell mode follows \fB$SHELL\fR: zsh uses \fB\-ilc\fR, bash uses \fB\-ic\fR, and other shells use \fB\-lc\fR.
.TP
.B \-\-output\-selection \fIFILE\fR
Write the created worktree path to FILE. When set, stdout output is suppressed.
.
.SS rename
Rename a worktree without launching the TUI.
.
.PP
Renames the worktree directory. The branch is renamed only when the current worktree directory name matches the branch name.
Shell completion for the first rename argument suggests available worktree basenames.
.
.PP
.B Options:
.TP
.B \fINEW\-NAME\fR
New worktree name. It is sanitised to lowercase letters, numbers, and hyphens. When given as the only argument, the current worktree (detected from the working directory) is renamed.
.
.TP
.B \fIWORKTREE\fR \fINEW\-NAME\fR
When two arguments are given, \fIWORKTREE\fR is the worktree path, branch name, or directory name to rename, and \fINEW\-NAME\fR is the new name. If no arguments are given, lazyworktree lists available worktrees and prints usage.
.
.TP
.B \-\-silent
Suppress all progress messages to stderr. Useful for scripting and automation.
.
.SS delete
Delete a worktree without launching the TUI.
.
.PP
Auto-detects the current worktree from the working directory. If not in a worktree, shows a selection list. Automatically deletes the associated branch if the worktree directory name matches the branch name.
Shell completion for the first delete argument suggests available worktree basenames.
.
.PP
.B Options:
.TP
.B \-\-no\-branch
Skip branch deletion entirely (even if worktree name matches branch name).
.
.TP
.B \-\-silent
Suppress all progress messages to stderr. Useful for scripting and automation.
.
.SS exec
Run a command or trigger a custom command key action in a worktree from the CLI.
.
.PP
The exec subcommand bridges CLI scripting with the TUI's custom command system, allowing you to execute shell commands or trigger tmux/zellij sessions without entering the TUI.
.
.PP
.B Options:
.TP
.B \fICOMMAND\fR
Optional positional argument for the shell command to execute. Mutually exclusive with \-\-key. The command runs through your shell environment (\fB$SHELL\fR) with appropriate flags (\fBzsh -ilc\fR, \fBbash -ic\fR, or fallback \fB-lc\fR).
.
.TP
.B \-\-workspace \fINAME\fR, \-w \fINAME\fR
Target worktree by name, path, or branch name. If not provided, lazyworktree auto-detects the worktree from the current directory. Shell completion suggests available worktree names.
.
.TP
.B \-\-key \fIKEY\fR, \-k \fIKEY\fR
Custom command key to trigger (e.g., 't' for tmux, 'z' for zellij). Mutually exclusive with the positional command argument. The key must exist in your configuration's \fBcustom_commands\fR. Supports shell, tmux, zellij, and show-output command types. Note: new-tab commands are not supported in CLI mode.
.
.PP
.B Environment:
.PP
The exec command sets the same \fBWORKTREE_*\fR environment variables as custom commands in the TUI:
.TP
.B WORKTREE_PATH
The absolute path to the worktree directory.
.TP
.B WORKTREE_BRANCH
The branch name of the worktree.
.TP
.B WORKTREE_NAME
The basename of the worktree directory.
.TP
.B REPO_NAME
The repository name.
.TP
.B MAIN_WORKTREE_PATH
The path to the main worktree.
.
.SH EXAMPLES
.SS Worktree Management
List worktrees (table format):
.br
.B lazyworktree list
.
.PP
List worktrees (paths only, suitable for scripting):
.br
.B lazyworktree list \-\-pristine
.
.PP
List worktrees as JSON:
.br
.B lazyworktree list \-\-json
.
.PP
Create from current branch (auto-generated name):
.br
.B lazyworktree create
.
.PP
Create from current branch with explicit name:
.br
.B lazyworktree create my\-feature
.
.PP
Create from specific branch:
.br
.B lazyworktree create \-\-from\-branch feature/new\-feature
.
.PP
Create from specific branch with explicit name:
.br
.B lazyworktree create \-\-from\-branch main my\-feature
.
.PP
Create from PR number:
.br
.B lazyworktree create \-\-from\-pr 123
.
.PP
Create from issue number (base: current branch):
.br
.B lazyworktree create \-\-from\-issue 42
.
.PP
Create from issue number with explicit base branch:
.br
.B lazyworktree create \-\-from\-issue 42 \-\-from\-branch main
.
.PP
Interactively select a PR (fzf or numbered list):
.br
.B lazyworktree create \-P
.
.PP
Interactively select a PR, pre\-filtered:
.br
.B lazyworktree create \-P \-q "dark"
.
.PP
Interactively select an issue, pre\-filtered:
.br
.B lazyworktree create \-I \-\-query "login"
.
.PP
Checkout PR branch without creating a worktree:
.br
.B lazyworktree create \-\-from\-pr 123 \-\-no\-workspace
.
.PP
Checkout issue branch without creating a worktree:
.br
.B lazyworktree create \-\-from\-issue 42 \-\-no\-workspace
.
.PP
Interactively select issue and checkout without creating a worktree:
.br
.B lazyworktree create \-I \-\-no\-workspace
.
.PP
Interactively select PR and checkout without creating a worktree:
.br
.B lazyworktree create \-P \-\-no\-workspace
.
.PP
Create with uncommitted changes:
.br
.B lazyworktree create my\-feature \-\-with\-change
.
.PP
Create and run a setup command in the new worktree:
.br
.B lazyworktree create my\-feature \-\-exec "npm install"
.
.PP
Delete worktree (and branch if name matches):
.br
.B lazyworktree delete
.
.PP
Delete worktree without deleting branch:
.br
.B lazyworktree delete \-\-no\-branch
.
.PP
Rename the current worktree (detected from cwd):
.br
.B lazyworktree rename new\-feature
.
.PP
Rename a worktree by name:
.br
.B lazyworktree rename feature new\-feature
.
.PP
Rename by path:
.br
.B lazyworktree rename /path/to/worktree new\-worktree
.
.PP
Run a command in a specific worktree:
.br
.B lazyworktree exec \-\-workspace=my\-feature "make test"
.
.PP
Run a command in the current worktree (auto-detected):
.br
.B lazyworktree exec "npm run build"
.
.PP
Trigger a tmux custom command:
.br
.B lazyworktree exec \-\-key=t \-\-workspace=my\-feature
.
.PP
Trigger a zellij custom command in the current worktree:
.br
.B lazyworktree exec \-k z
.
.SS TUI Launch
Launch the TUI (default):
.br
.B lazyworktree
.
.PP
Launch with custom worktree directory:
.br
.B lazyworktree \-\-worktree\-dir ~/worktrees
.
.PP
Override theme via CLI:
.br
.B lazyworktree \-\-config lw.theme=nord
.
.SS Shell Completion
Generate zsh completion:
.br
.B lazyworktree \-\-completion zsh > ~/.zsh/completions/_lazyworktree
.
.PP
Generate bash completion:
.br
.B lazyworktree \-\-completion bash > /etc/bash_completion.d/lazyworktree
.
.PP
Generate fish completion:
.br
.B lazyworktree \-\-completion fish > ~/.config/fish/completions/lazyworktree.fish
.
.SH KEY BINDINGS
.SS General Navigation
.TP
.B j, k, Up, Down
Navigate between items in the focused pane or selection menus.
.
.TP
.B Home
Go to first item in focused pane.
.
.TP
.B End
Go to last item in focused pane.
.
.TP
.B h, l
Shrink/grow worktree pane (h=shrink, l=grow).
.
.TP
.B Tab, ]
Cycle to next pane.
.
.TP
.B [
Cycle to previous pane.
.
.TP
.B 1
Switch to Worktree pane (toggle zoom if already focused).
.
.TP
.B 2
Switch to Status pane (toggle zoom if already focused).
.
.TP
.B 3
Switch to Git Status pane (toggle zoom if already focused).
.
.TP
.B 4
Switch to Commit pane (toggle zoom if already focused).
.
.TP
.B 5
Switch to Notes pane (toggle zoom if already focused). Only visible when the
selected worktree has a note. Tab cycling includes this pane when visible.
.
.TP
.B =
Toggle zoom for focused pane (full screen, press again to unzoom).
.
.TP
.B L
Toggle layout between default (worktrees left with notes below when present, status/git status/commit stacked right) and
top (worktrees full-width top, notes row below when present, status/git status/commit side-by-side bottom).
.
.TP
.B y
Copy to clipboard (context-aware: worktree path in worktrees pane, file path in
git status pane, commit SHA in commit pane). Uses OSC52, works over SSH.
.
.TP
.B Y
Copy the selected worktree's branch name to the clipboard.
.
.TP
.B ?
Show help screen.
.
.TP
.B q
Quit application.
.
.SS Worktree Operations
.TP
.B Enter
Jump to worktree (exit and cd), or open commit file tree in commit pane.
.
.TP
.B d
Show diff in pager for the selected worktree (or selected commit in the commit pane).
.
.TP
.B c
Create new worktree (from branch, commit, PR/MR, or issue).
.
.TP
.B i
Open selected worktree notes. If a note exists, a viewer opens first; if no note exists, the editor opens directly. In the note viewer, j/k (or arrow keys) scroll, Ctrl+D/Ctrl+U move half a page, g/G jump to top/bottom, e opens edit mode, and q/Esc closes. In the note editor, Ctrl+S saves, Ctrl+X opens the note in an external editor, Enter inserts a new line, and Esc cancels. Worktrees with non-empty notes show a note marker beside the name. In the Info pane, notes render Markdown for headings, bold text, inline code, lists, quotes, links, and fenced code blocks. Uppercase note tags such as TODO, FIXME, or WARNING: are highlighted with icons outside fenced code blocks. Lowercase tags are left unchanged.
.
.TP
.B T
Open Taskboard, a Kanban-lite view grouped by worktree that reads markdown checkbox items from notes (for example, \fB- [ ] draft release notes\fR). Use j/k to move, Enter or Space to toggle completion, a to add a new task, f to filter tasks, and q/Esc to close.
.
.TP
.B m
Rename selected worktree.
.
.TP
.B D
Delete selected worktree.
.
.TP
.B A
Absorb worktree into main (merge or rebase based on configuration).
.
.TP
.B X
Prune merged worktrees. Automatically refreshes PR/MR data from GitHub or GitLab (if connected), then detects worktrees whose associated PR has been merged or whose branch has been merged into the main branch. For repositories without GitHub/GitLab remotes, uses git-based merge detection only. Displays a checklist allowing selection of which worktrees to remove.
.
.TP
.B !
Run arbitrary command in selected worktree.
.
.TP
.B r
Refresh worktree list (also refreshes PR/MR/CI for current worktree on GitHub/GitLab).
.
.TP
.B R
Fetch all remotes.
.
.TP
.B S
Synchronise with upstream (git pull, then git push, current branch only, requires a clean worktree, honours merge_method).
.
.TP
.B P
Push to upstream branch. Current branch only, requires a clean worktree and prompts to set upstream when missing.
.
.TP
.B s
Cycle sort mode (Path / Last Active / Last Switched).
.
.SS Status Pane
The Status pane displays PR info, CI checks, notes, and divergence status.
In terminals that support OSC-8 hyperlinks, the PR/MR number in the info panel is clickable.
.
.TP
.B j, k
Navigate CI checks (when visible).
.
.TP
.B Enter
Open selected CI check URL in browser.
.
.TP
.B Ctrl+v
View selected CI check logs in pager.
.
.TP
.B Ctrl+r
Restart CI job (GitHub Actions only).
.
.SS Git Status Pane
The Git Status pane displays changed files in a collapsible tree view, grouped by directory. Directories are shown with expand/collapse indicators and can be toggled with Enter. Files are sorted alphabetically within each directory level and include icons from the selected icon set when enabled.
.
.TP
.B Enter
Toggle directory expand/collapse, or show diff for selected file.
.
.TP
.B s
Stage/unstage selected file or directory.
.
.TP
.B D
Delete selected file or directory (with confirmation).
.
.TP
.B e
Open selected file in editor.
.
.TP
.B c
Commit staged changes.
.
.TP
.B C
Stage all changes and commit.
.
.TP
.B d
Show full diff (all files) in pager.
.
.TP
.B ctrl+Left, ctrl+Right
Jump to previous/next folder.
.
.TP
.B /
Search file or directory names (incremental).
.
.TP
.B Ctrl+d, Space
Half page down.
.
.TP
.B Ctrl+u
Half page up.
.
.TP
.B PageUp, PageDown
Half page up/down.
.
.SS Commit Pane
.TP
.B j, k, Up, Down
Move between commits.
.
.TP
.B Enter
Open commit file tree view.
.
.TP
.B d
Show full commit diff in pager.
.
.TP
.B C
Cherry-pick commit to another worktree (interactive picker).
.
.TP
.B ctrl+j
Move to next commit and open commit file tree.
.
.TP
.B /
Search commit titles (incremental).
.
.SS Commit File Tree
When pressing Enter on a commit in the commit pane, a file tree view opens showing all files changed in that commit. The tree is collapsible by directory and includes icons from the selected icon set when enabled.
.
.TP
.B j, k, Up, Down
Navigate files and directories.
.
.TP
.B Enter
Toggle directory expand/collapse, or show diff for selected file.
.
.TP
.B d
Show full commit diff in pager.
.
.TP
.B f
Filter files by name.
.
.TP
.B /
Search files (incremental).
.
.TP
.B n, N
Next/previous search match.
.
.TP
.B Ctrl+d, Space
Half page down.
.
.TP
.B Ctrl+u
Half page up.
.
.TP
.B g, G
Jump to top/bottom.
.
.TP
.B q, Esc
Return to commit log.
.
.SS Filter and Search
.TP
.B f
Filter focused pane by fuzzy matching. When a filter is active, the pane title shows a filter indicator with [Esc] Clear hint. Filtering narrows the visible items to those matching your input. In selection menus, press f to show the filter input; Esc returns to the list and keeps the current filter.
.
.TP
.B Alt+n, Alt+p
Move selection and fill filter input (worktree filter only).
.
.TP
.B Up, Down, Ctrl+j, Ctrl+k
Move selection without changing filter input.
.
.TP
.B /
Search focused pane incrementally. Unlike filter, search highlights matches whilst keeping all items visible. Use n/N to navigate between matches.
.
.TP
.B n
Jump to next search match.
.
.TP
.B N
Jump to previous search match.
.
.TP
.B Esc
Clear filter for focused pane (when filter is active).
.
.SS Forge Integration
.TP
.B v
View CI checks (Enter opens in browser, Ctrl+v views logs in pager).
.
.TP
.B Enter
Open selected CI job in browser (within CI check selection).
.
.TP
.B Ctrl+v
View selected CI check logs in pager (within CI check selection).
.
.TP
.B Ctrl+r
Restart selected CI job (GitHub Actions only, within CI check selection).
.
.TP
.B o
Open PR/MR in browser (or root repository in editor if main branch with merged/closed/no PR).
.
.SS Command Palette
.TP
.B ctrl+p, :
Open command palette showing all available commands (e.g. select theme).

The palette exposes a "Create from current" entry which copies the branch you currently occupy. When uncommitted files exist, the prompt shows an "Include current file changes" checkbox; Tab/Shift+Tab focuses it and Space toggles it. When selected, the diff is passed to any configured `branch_name_script` for naming suggestions.

The command palette automatically lists all active tmux and zellij sessions starting with the configured session prefix (default: \fBwt-\fR) under separate "Active Tmux Sessions" and "Active Zellij Sessions" sections that appear after the Multiplexer section, allowing you to quickly switch to existing sessions without manually typing session names. The session prefix can be customised via the \fBsession_prefix\fR configuration option. Note that tmux does not permit colons (:) in session names, so any colons in the prefix will be automatically converted to hyphens (-).
.
.SS LazyGit
.TP
.B g
Open LazyGit for the currently selected worktree.
.
.SS Tips
.PP
The loading modal shows contextual tips based on the current operation (for example refresh, fetch, synchronise, push, or CI rerun). When multiple tips are available for the same context, lazyworktree avoids showing the same tip consecutively.
.
.PP
Curated tips are also listed in the in-application Help screen under "Tips & Shortcuts".
.
.SH MOUSE SUPPORT
lazyworktree provides comprehensive mouse support for improved navigation and interaction:
.
.TP
.B Click on pane
Focus the clicked pane (Worktree, Status, Git Status, Commit, or Notes).
.
.TP
.B Click on item
Select the clicked item in a table or list.
.
.TP
.B Mouse wheel
Scroll up or down in the focused pane.
.
.PP
Mouse support works in all panes and is particularly useful for quickly switching context or selecting specific items without keyboard navigation.
.
.SH SHELL INTEGRATION
To enable the "jump" functionality, source the helper functions from the installation:
.
.PP
For source builds:
.RS
.nf
source /path/to/lazyworktree/shell/functions.zsh
jt() { worktree_jump ~/path/to/your/main/repo "$@"; }
.fi
.RE
.
.PP
For Homebrew:
.RS
.nf
source $(brew --prefix)/opt/lazyworktree/share/lazyworktree/functions.zsh
jt() { worktree_jump ~/path/to/your/main/repo "$@"; }
.fi
.RE
.
.PP
With completion (zsh):
.RS
.nf
_jt() { _worktree_jump ~/path/to/your/main/repo; }
compdef _jt jt
.fi
.RE
.
.SH BRANCH NAMING CONVENTIONS
When creating worktrees with manual branch names, special characters are automatically converted to hyphens for compatibility with Git and terminal multiplexers (tmux/zellij). This ensures worktree directories and session names are valid across all systems.
.PP
.SS Supported Characters
.LP
Branch names can contain:
.IP \(bu 2
Letters (a-z, A-Z)
.IP \(bu 2
Numbers (0-9)
.IP \(bu 2
Hyphens (-)
.LP
All other characters are automatically converted to hyphens.
.PP
.SS Character Conversions
.LP
.TS
tab(|) allbox;
l l l.
Input|Converted|Reason
_
feature.new|feature-new|Dots not allowed in Git branch names
bug fix here|bug-fix-here|Spaces not allowed in branch names
path/to/branch|path-to-branch|Slashes reserved for path separators
feature:test|feature-test|Colons reserved in tmux/zellij session names
test_underscore|test-underscore|Normalised to hyphens for consistency
.TE
.PP
.SS Rules
.LP
.IP \(bu 2
Leading and trailing hyphens are removed
.IP \(bu 2
Consecutive hyphens are collapsed to a single hyphen
.IP \(bu 2
Maximum length: 50 characters (manual input), 100 characters (auto-generated names)

.SH CONFIGURATION
lazyworktree reads configuration from multiple sources with the following precedence (highest to lowest):
.IP 1. 4
CLI overrides (using \fB--config\fR flag)
.IP 2. 4
Git local configuration (repository-specific via \fBgit config --local\fR)
.IP 3. 4
Git global configuration (user-wide via \fBgit config --global\fR)
.IP 4. 4
YAML configuration file (\fB~/.config/lazyworktree/config.yaml\fR or \fBconfig.yml\fR)
.IP 5. 4
Built-in defaults
.
.SS Git Configuration
Settings can be stored in Git's configuration system with the \fBlw.\fR prefix:
.
.RS
.nf
# Set globally
git config --global lw.theme nord
git config --global lw.worktree_dir ~/.local/share/worktrees

# Set per-repository (overrides global)
git config --local lw.theme dracula
git config --local lw.init_commands "link_topsymlinks"
git config --local lw.init_commands "npm install"  # Multi-values supported

# View all lazyworktree settings
git config --global --get-regexp "^lw\."
git config --local --get-regexp "^lw\."
.fi
.RE
.PP
This allows flexible configuration at different levels. For example, set a default theme globally and override it per-repository, or temporarily change settings via the command line with \fB--config\fR.
.PP
lazyworktree reads \fB~/.config/lazyworktree/config.yaml\fR (or \fBconfig.yml\fR) for default settings. An example configuration is provided below (also available in \fBconfig.example.yaml\fR).
.
.SS General Settings
.TP
.B worktree_dir
Default worktree root directory. Worktrees are organised under ~/.local/share/worktrees/<repo_name> by default. The application attempts to resolve repository locations via \fBgh repo view\fR or \fBglab repo view\fR. If the repository name is not detectable, lazyworktree falls back to a local \fBlocal-<hash>\fR key for cache and last-selected storage.
.br
Default: ~/.local/share/worktrees
.br
Can be overridden with \fB--worktree-dir\fR.
.
.TP
.B worktree_notes_path
Optional path to store all worktree notes in a single shared JSON file.
.br
When set, notes are keyed by repository/worktree-relative identifiers rather than absolute paths, which helps with synchronisation across systems.
.br
Default: empty (per-repository \fB.worktree-notes.json\fR files under \fBworktree_dir\fR)
.
.TP
.B sort_mode
Default sort order for worktrees.
.br
Options: \fBpath\fR (alphabetical), \fBactive\fR (last commit date), \fBswitched\fR (last accessed).
.br
Default: switched
.br
Note: The old \fBsort_by_active\fR option is still supported for backwards compatibility.
.
.TP
.B layout
Pane arrangement.
.br
Options: \fBdefault\fR (worktrees left with notes below when present, status/log stacked right), \fBtop\fR (worktrees full-width top, notes row below when present, status/log side-by-side bottom).
.br
Default: default
.br
Can be toggled at runtime with the \fBL\fR key.
.
.TP
.B layout_sizes
Configurable pane size weights. Each sub-key accepts an integer between 1 and 100.
Values are relative weights that are normalised at computation time, so
\fBinfo: 30, git_status: 30, commit: 30\fR means each receives one-third of the
secondary area. Omitted fields keep their built-in defaults.
Focus-based dynamic resizing still applies on top of the configured baseline.
.br
Sub-keys: \fBworktrees\fR (main pane width or height), \fBinfo\fR, \fBgit_status\fR,
\fBcommit\fR, \fBnotes\fR.
.br
Default: unset (built-in ratios used).
.
.TP
.B search_auto_select
Start with filter focused and select first match on Enter.
.br
Default: false
.br
Can also be enabled with \fB--search-auto-select\fR.
.
.TP
.B auto_refresh
Refresh git metadata and working tree status in the background.
.br
Default: true
.br
Set to false to rely on manual refresh (r).
.
.TP
.B refresh_interval
Background refresh interval in seconds.
.br
Default: 10
.br
Set to 0 to disable timed refreshes.
.
.TP
.B ci_auto_refresh
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).
.br
Default: false
.
.TP
.B disable_pr
Disable all PR/MR fetching and display. When enabled, no GitHub/GitLab API calls
are made for PR/MR data, the PR column is hidden from the worktree table, and
CI status fetching is disabled. Useful for repositories not hosted on GitHub or
GitLab, or when PR/MR integration is not desired.
.br
Default: false
.
.TP
.B debug_log
Path to debug log file for troubleshooting. When set, detailed debug information is written to this file.
.br
Can also be set with \fB--debug-log\fR.
.
.SS User Interface
.TP
.B theme
UI colour theme. If left empty or unspecified, the theme is auto-detected from the terminal background.
.br
Available built-in themes: \fBdracula\fR (default for dark), \fBdracula-light\fR (default for light), \fBnarna\fR, \fBclean-light\fR, \fBcatppuccin-latte\fR, \fBrose-pine-dawn\fR, \fBone-light\fR, \fBeverforest-light\fR, \fBeverforest-dark\fR, \fBsolarized-dark\fR, \fBsolarized-light\fR, \fBgruvbox-dark\fR, \fBgruvbox-light\fR, \fBnord\fR, \fBmonokai\fR, \fBcatppuccin-mocha\fR, \fBmodern\fR, \fBtokyo-night\fR, \fBone-dark\fR, \fBrose-pine\fR, \fBayu-mirage\fR, \fBkanagawa\fR.
.br
Custom themes can be defined in the configuration file (see \fBcustom_themes\fR below) and will appear alongside built-in themes in the theme selection screen.
.br
Can also be set with \fB--theme\fR.
.
.TP
.B icon_set
Choose icon set. Options: "nerd-font-v3", "text".
.br
Applies to file icons, UI indicators, and help headings.
.br
The text set uses plain labels.
.br
If icons render as placeholder glyphs, set icon_set to text or install a font patched with Nerd Font.
.br
Default: "nerd-font-v3"
.
.TP
.B fuzzy_finder_input
Enable fuzzy finder suggestions in input dialogues. When enabled, typing in text input fields displays fuzzy-filtered suggestions from available options. Use arrow keys to navigate suggestions and Enter to select.
.br
Default: false
.
.TP
.B palette_mru
Enable MRU (Most Recently Used) sorting for the command palette. When enabled, a "Recently Used" section appears at the top of the palette showing your most frequently used commands. Usage history is stored per-repository in .command-palette-history.json.
.br
Default: true
.
.TP
.B palette_mru_limit
Number of recent commands to show in the command palette MRU section. Only applies when palette_mru is enabled.
.br
Default: 8
.
.TP
.B max_untracked_diffs
Maximum number of untracked file diffs to show. Set to 0 to hide untracked diffs.
.br
Default: 10
.
.TP
.B max_diff_chars
Maximum characters to display in diffs before truncation. Set to 0 to disable truncation.
.br
Default: 200000
.
.TP
.B max_name_length
Maximum length for worktree names displayed in the table. Names longer than this limit will be truncated with "..." appended. Set to 0 to disable truncation entirely.
.br
Default: 95
.
.SS Diff and Pager
.TP
.B git_pager
Diff formatter/pager command (default: delta). Set to empty string to disable diff formatting and use plain git diff output.
.br
You may also use alternatives such as diff-so-fancy.
.br
VS Code users can set git_pager: code to open diffs via git difftool with proper side-by-side comparison (one window per file).
.br
Default: delta
.
.TP
.B git_pager_args
List of extra arguments passed to git_pager for diff rendering.
.br
If omitted and git_pager is delta, lazyworktree picks a syntax theme matching your UI theme.
.br
Default mappings: dracula → Dracula, dracula-light → Monokai Extended Light, narna → OneHalfDark, clean-light → GitHub, catppuccin-latte → Catppuccin Latte, rose-pine-dawn → GitHub, one-light → OneHalfLight, everforest-light → Gruvbox Light, solarized-dark → Solarized (dark), solarized-light → Solarized (light), gruvbox-dark → Gruvbox Dark, gruvbox-light → Gruvbox Light, nord → Nord, monokai → Monokai Extended, catppuccin-mocha → Catppuccin Mocha.
.br
Use \fB--show-syntax-themes\fR to display default values.
.
.TP
.B git_pager_interactive
Enables interactive diff viewers requiring terminal control (default: false).
.br
Set to true for tools like diffnav, ftdv, or tig that provide keyboard navigation.
.br
When enabled, only unstaged changes (git diff) are shown.
.br
Non-interactive formatters like delta and diff-so-fancy should keep this false.
.
.TP
.B git_pager_command_mode
Enables command-based diff viewers that run their own git commands (default: false).
.br
Set to true for tools like lumen that accept subcommands such as \fBlumen diff\fR, \fBlumen diff <commit>\fR.
.br
When enabled, lazyworktree calls \fB<git_pager> diff [args...]\fR directly instead of piping git diff output.
.
.TP
.B pager
Pager command for show_output custom commands and diff viewer.
.br
Default: $PAGER, fallback: less --use-co\%lor --wordwrap -qcR -P 'Press q to exit..', then more, then cat.
.br
When the pager is less, lazyworktree configures LESS= and LESSHISTFILE=- to ignore user defaults.
.
.TP
.B ci_script_pager
Pager command for CI check logs.
.br
When set, runs interactively with direct terminal control (no set -o pipefail or environment adjustments).
.br
Falls back to pager if not configured.
.br
Example: ci_script_pager: "less -R" or ci_script_pager: "bat --style=plain"
.PP
CI-specific environment variables available to ci_script_pager:
.RS
.IP \(bu 2
LW_CI_JOB_NAME \- Name of the CI check/job
.IP \(bu 2
LW_CI_JOB_NAME_CLEAN \- Sanitised job name suitable for filenames (lowercase, hyphens only)
.IP \(bu 2
LW_CI_RUN_ID \- GitHub Actions run ID (extracted from check URL)
.IP \(bu 2
LW_CI_STARTED_AT \- Job start time in ISO 8601 format (if available)
.RE
.
.TP
.B editor
Editor command for Status pane file edits.
.br
Default: config value, then $EDITOR, then nvim, then vi.
.
.SS Forge Integration
.TP
.B issue_branch_name_template
Template for branch names created from GitHub/GitLab issues. Available placeholders: \fB{number}\fR (issue number), \fB{title}\fR (sanitised issue title), and \fB{generated}\fR (generated title from branch_name_script, falls back to {title} if unavailable).
.br
Default: issue-{number}-{title}
.br
Example: With template "fix-{number}-{title}", issue #42 titled "Memory Leak" becomes branch "fix-42-memory-leak". With template "issue-{number}-{generated}" and a script configured, the generated title is used instead.
.
.TP
.B pr_branch_name_template
Template for worktree names created from pull/merge requests. Available placeholders: \fB{number}\fR (PR/MR number), \fB{title}\fR (sanitised PR/MR title), \fB{pr_author}\fR (sanitised PR author username), and \fB{generated}\fR (generated title from branch_name_script, falls back to {title} if unavailable).
.br
Default: pr-{number}-{title}
.br
Example: With template "review-{number}", PR #123 becomes worktree name "review-123". With template "pr-{number}-{pr_author}-{generated}", PR #123 by alice can become "pr-123-alice-feat-fix-ci".
.
.SS Security and Behaviour
.TP
.B trust_mode
Security setting for executing commands from .wt files.
.br
Options: \fBtofu\fR (default - prompts on first use/change), \fBnever\fR (never run commands), \fBalways\fR (always run without prompting, risky).
.
.TP
.B merge_method
Merge method for "Absorb worktree" and "Synchronise with upstream" actions.
.br
Options: \fBrebase\fR (default - rebases onto main then fast-forwards, synchronise uses \fBgit pull --rebase=true\fR), \fBmerge\fR (creates merge commit and uses a standard \fBgit pull\fR).
.
.SS Automation
.TP
.B branch_name_script
Script to generate branch name suggestions when creating worktrees from changes, issues, or PRs. For issues/PRs, the script should output a title (e.g., "feat-ai-session-manager") which will be sanitised and made available via the \fB{generated}\fR placeholder in your configured template. For diffs, the script should output a complete branch name. The script receives content on stdin (git diff for changes, issue/PR title and body for issues/PRs). First line of output is used.
.br
Available environment variables: LAZYWORKTREE_TYPE (pr/issue/diff), LAZYWORKTREE_NUMBER (PR/issue number), LAZYWORKTREE_TEMPLATE (configured template), LAZYWORKTREE_SUGGESTED_NAME (template-generated name using original PR/issue title).
.br
Script operates under a 30-second timeout.
.
.TP
.B worktree_note_script
Script to generate an initial worktree note when creating from a PR/MR or issue. The script receives title and body content on stdin and may return multiline output. If the script fails or returns empty output, worktree creation continues and no note is saved.
.br
Available environment variables: LAZYWORKTREE_TYPE (pr/issue), LAZYWORKTREE_NUMBER, LAZYWORKTREE_TITLE, LAZYWORKTREE_URL.
.br
Script operates under a 30-second timeout.
.
.TP
.B init_commands
List of commands to execute when creating a worktree. These execute before any repository-specific .wt commands (if present).
.br
Available environment variables: WORKTREE_BRANCH, MAIN_WORKTREE_PATH, WORKTREE_PATH, WORKTREE_NAME.
.br
Special built-in command: \fBlink_topsymlinks\fR (not a shell command) symlinks untracked/ignored files from main worktree root, non-empty editor configs (.vscode, .idea, .cursor, .claude/settings.local.json) if it exists, ensures tmp/ directory exists, and runs direnv allow if .envrc is present.
.
.TP
.B terminate_commands
List of commands to execute when removing a worktree. These execute before any repository-specific .wt commands (if present).
.br
Same environment variables as init_commands.
.
.TP
.B custom_commands
Custom keybindings to run commands in the selected worktree. Commands execute interactively (TUI suspends, like lazygit) and appear in the command palette. Custom commands take precedence over built-in keys.
.PP
Each custom command supports the following fields:
.RS
.IP \(bu 2
\fBcommand\fR: The command to execute (required, unless using tmux/zellij)
.IP \(bu 2
\fBdescription\fR: Description shown in help screen and command palette (optional)
.IP \(bu 2
\fBshow_help\fR: Show in help screen and footer hints (default: false)
.IP \(bu 2
\fBwait\fR: Wait for key press after command completes (default: false, useful for quick commands)
.IP \(bu 2
\fBshow_output\fR: Run non-interactively and show stdout/stderr in the pager (default: false, ignores wait)
.IP \(bu 2
\fBnew_tab\fR: Launch command in a new terminal tab (default: false). Can be combined with \fBtmux\fR and \fBzellij\fR to open multiplexer sessions in new tabs instead of suspending the TUI. Currently supports Kitty (requires remote control enabled), WezTerm, and iTerm.
.IP \(bu 2
\fBtmux\fR: Configure a tmux session instead of executing a single command (object, optional)
.IP \(bu 2
\fBzellij\fR: Configure a zellij session instead of executing a single command (object, optional)
.RE
.PP
Supported key formats: single keys (e, s, t), modifier combinations (ctrl+e, alt+t), special keys (enter, esc, tab, space).
.PP
Environment variables available in custom commands: WORKTREE_BRANCH, MAIN_WORKTREE_PATH, WORKTREE_PATH, WORKTREE_NAME, REPO_NAME.
.PP
For tmux sessions, the following fields are available:
.RS
.IP \(bu 2
\fBsession_name\fR: tmux session name, supports env vars (default: wt:$WORKTREE_NAME). Colons, slashes, and backslashes are replaced with -.
.IP \(bu 2
\fBattach\fR: If true, attach/switch immediately; if false, show info modal (default: true)
.IP \(bu 2
\fBon_exists\fR: Behaviour if session exists: switch, attach, kill, new (default: switch)
.IP \(bu 2
\fBwindows\fR: List of window definitions. Each window has: name (supports env vars), command (empty uses default shell), cwd (default: $WORKTREE_PATH). If omitted, creates a single shell window.
.RE
.PP
For zellij sessions, the following fields are available:
.RS
.IP \(bu 2
\fBsession_name\fR: zellij session name, supports env vars (default: wt:$WORKTREE_NAME). Colons, slashes, and backslashes are replaced with -.
.IP \(bu 2
\fBattach\fR: If true, attach immediately; if false, show info modal (default: true)
.IP \(bu 2
\fBon_exists\fR: Behaviour if session exists: switch, attach, kill, new (default: switch)
.IP \(bu 2
\fBwindows\fR: List of tab definitions. Each tab has: name (supports env vars), command (empty uses default shell), cwd (default: $WORKTREE_PATH). If omitted, creates a single shell tab.
.RE
.
.TP
.B custom_create_menus
Custom items for the worktree creation menu (triggered by \fBc\fR key). The workflow: you first select a base branch, then the command runs to generate a branch name, and optionally a post-command runs after worktree creation.
.PP
Each custom create menu entry supports the following fields:
.RS
.IP \(bu 2
\fBlabel\fR: Display label shown in the menu (required)
.IP \(bu 2
\fBdescription\fR: Help text shown next to the label (optional)
.IP \(bu 2
\fBcommand\fR: Shell command that outputs a branch name on stdout (required)
.IP \(bu 2
\fBinteractive\fR: Run interactively (default: false). Set to true for TUI-based commands like fzf or jayrah. When true, lazyworktree suspends, the command runs in the terminal, and stdout is captured via a temp file.
.IP \(bu 2
\fBpost_command\fR: Command to run in the new worktree directory after creation (optional). Runs after global/repo init_commands. Has access to environment variables like WORKTREE_BRANCH, WORKTREE_PATH, etc.
.IP \(bu 2
\fBpost_interactive\fR: Run post-command interactively (default: false). When true, the TUI suspends to show command I/O.
.RE
.PP
By default, commands run non-interactively with a 30-second timeout. When \fBinteractive: true\fR, there is no timeout. The command output (first line only, whitespace trimmed, case preserved) is used as the suggested branch name. Post-commands are useful for automated setup tasks like creating initial commits, installing dependencies, or opening editors. If a post-command fails, the error is shown but the worktree is kept. This feature is useful for integrating external tools like JIRA, Linear, or custom scripts.
.PP
Example configuration:
.RS
.nf
custom_create_menus:
  - label: "From JIRA ticket"
    description: "Create from JIRA issue"
    command: "jayrah browse 'SRVKP' --choose"
    interactive: true
    post_command: "git commit --allow-empty -m 'Initial commit for ${WORKTREE_BRANCH}'"
    post_interactive: false
.fi
.RE
.
.TP
.B custom_themes
Define custom themes that can inherit from built-in themes or other custom themes. Custom themes allow you to personalise the colour scheme without modifying code.
.br
Two ways to define a custom theme:
.RS
.IP 1. 4
Inherit from a built-in theme and override specific colours:
.RS
.nf
custom_themes:
  my-dark:
    base: dracula
    accent: "#FF6B9D"
    text_fg: "#E8E8E8"
.fi
.RE
.IP 2. 4
Define a complete theme without a base (all 11 colour fields required):
.RS
.nf
custom_themes:
  completely-custom:
    accent: "#00FF00"
    accent_fg: "#000000"
    accent_dim: "#2A2A2A"
    border: "#3A3A3A"
    border_dim: "#2A2A2A"
    muted_fg: "#888888"
    text_fg: "#FFFFFF"
    success_fg: "#00FF00"
    warn_fg: "#FFFF00"
    error_fg: "#FF0000"
    cyan: "#00FFFF"
.fi
.RE
.RE
.PP
Custom themes can also inherit from other custom themes. Available colour fields (snake_case in YAML): \fBaccent\fR, \fBaccent_fg\fR, \fBaccent_dim\fR, \fBborder\fR, \fBborder_dim\fR, \fBmuted_fg\fR, \fBtext_fg\fR, \fBsuccess_fg\fR, \fBwarn_fg\fR, \fBerror_fg\fR, \fBcyan\fR.
.br
Colour values must be in hex format (\fB#RRGGBB\fR or \fB#RGB\fR). When using a \fBbase\fR theme, only specify colours you want to override. When not using a base, all 11 colour fields are required.
.br
Custom themes appear in the theme selection screen alongside built-in themes.
.
.SS Example Configuration
A practical configuration demonstrating common settings:
.PP
.RS
.nf
# UI and behaviour
theme: nord
icon_set: nerd-font-v3
sort_mode: switched
fuzzy_finder_input: true
auto_refresh: true
refresh_interval: 10
palette_mru: true
palette_mru_limit: 5

# Forge integration
issue_branch_name_template: "fix-{number}-{title}"
pr_branch_name_template: "pr-{number}-{generated}"

# Diff settings
git_pager: delta
max_diff_chars: 500000

# Security
trust_mode: tofu
merge_method: rebase

# Automation
init_commands:
  - link_topsymlinks
  - echo "Worktree ${WORKTREE_NAME} initialised"

# Custom commands
custom_commands:
  - key: t
    description: "Open tmux session"
    show_help: true
    tmux:
      session_name: "${REPO_NAME}_${WORKTREE_NAME}"
      attach: true
      on_exists: switch
      windows:
        - name: "editor"
          command: "nvim"
        - name: "shell"
          command: ""
.fi
.RE
.
.SH PREREQUISITES
.IP \(bu 2
Git 2.31+ (recommended)
.IP \(bu 2
Forge CLI: GitHub CLI (gh) or GitLab CLI (glab) for repository resolution and PR/MR status
.
.SH OPTIONAL DEPENDENCIES
.IP \(bu 2
delta \- For syntax-highlighted diffs
.IP \(bu 2
lazygit \- For full TUI git control
.IP \(bu 2
tmux \- For tmux integration support
.IP \(bu 2
zellij \- For zellij integration support
.
.SH EXAMPLES
.TP
Open lazyworktree:
.RS
.nf
lazyworktree
.fi
.RE
.
.TP
Specify custom worktree directory:
.RS
.nf
lazyworktree --worktree-dir ~/my-worktrees
.fi
.RE
.
.TP
Select a theme:
.RS
.nf
lazyworktree --theme nord
.fi
.RE
.
.TP
Use with shell function for "jump" functionality:
.RS
.nf
jt  # Opens TUI, select a worktree and press Enter to jump
.fi
.RE
.
.TP
Custom issue branch template in configuration:
.RS
.nf
issue_branch_name_template: "bug-{number}-{title}"
.fi
This will create branches like "bug-42-memory-leak" from issue #42.
.RE
.
.SH ENVIRONMENT
The following environment variables affect lazyworktree's behaviour when used with custom commands:
.IP \(bu 2
WORKTREE_BRANCH \- Name of the git branch
.IP \(bu 2
MAIN_WORKTREE_PATH \- Path to the main repository
.IP \(bu 2
WORKTREE_PATH \- Path to the selected worktree
.IP \(bu 2
WORKTREE_NAME \- Name of the worktree (directory name)
.IP \(bu 2
REPO_NAME \- Name of the repository (from GitHub/GitLab)
.
.SH CONFIGURATION FILES
.TP
.B ~/.config/lazyworktree/config.yaml
Main configuration file
.
.TP
.B ~/.local/share/lazyworktree/trusted.json
Trust on First Use (TOFU) trusted file hashes
.
.TP
.B ~/.local/share/worktrees/<repo-name>/
Default worktree storage location
.
.SH SEE ALSO
.BR git-worktree (1),
.BR lazygit (1),
.BR tmux (1),
.BR zellij (1),
.BR delta (1)
.
.SH AUTHOR
Chmouel Boudjnah <chmouel@chmouel.com>
.
.SH COPYRIGHT
Apache Licence 2.0
.
.SH REPORTING BUGS
Report bugs at https://github.com/chmouel/lazyworktree/issues