config.example.yaml

# ============================================================================
# CORE SETTINGS
# ============================================================================

# Directory where your worktrees will be created.
# lazyworktree automatically sets $LWT_REPO_PATH to the git repository root,
# so you can place worktrees inside the repository itself:
#   worktree_dir: $LWT_REPO_PATH/.worktrees
# In repo-local mode the <repoName> path segment is omitted, giving:
#   <repoRoot>/.worktrees/<worktreeName>
# Remember to add the directory to .gitignore (e.g. echo '.worktrees' >> .gitignore).
worktree_dir: ~/.local/share/worktrees

# How worktrees are sorted in the list
# Options: "path" (alphabetical), "active" (last commit date), "switched" (last accessed by you)
sort_mode: switched

# Pane arrangement
# Options: "default" (worktrees left, status/log stacked right),
#          "top" (worktrees full-width top, status/log side-by-side bottom)
# Toggle at runtime with L
layout: default

# Customise how much screen space each pane receives
# Values are relative weights (1–100) that are normalised at computation time.
# For example, info: 30, git_status: 30, commit: 30 gives each one-third of
# the secondary area. Omit any field to keep its built-in default.
# Focus-based dynamic resizing still applies on top of these baselines.
#
# layout_sizes:
#   worktrees: 55    # Main pane width (default layout) or height (top layout)
#   info: 30         # Info pane share of secondary area
#   git_status: 40   # Git status pane share (when visible)
#   commit: 30       # Commit log pane share
#   agent_sessions: 20 # Agent sessions pane share (when visible)
#   notes: 30        # Notes pane share (when visible)

# Refresh git metadata and working tree status in the background
# Set to false to rely on manual refresh (r)
auto_refresh: true

# Background refresh interval in seconds (lower this for more frequent updates)
refresh_interval: 10

# Periodically refresh CI status for GitHub repositories (default: false)
# 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).
ci_auto_refresh: false

# Git remote to target for CI and PR status queries on GitHub.
# When unset or set to "auto", an "upstream" remote is preferred when present,
# otherwise "origin". Set a remote name to target a specific remote without
# changing repository identity. GitLab MR/CI queries use glab's own repository
# resolution.
# ci_remote: origin

# Start with fuzzy finder input focused in selection screens
fuzzy_finder_input: false

# ============================================================================
# UI & DISPLAY
# ============================================================================

# TUI theme (default: "rose-pine" for dark terminals, "dracula-light" for light terminals)
# Options: "dracula", "dracula-light", "narna", "clean-light", "solarized-dark",
#          "solarized-light", "gruvbox-dark", "gruvbox-light", "nord", "monokai",
#          "catppuccin-mocha", "modern", "tokyo-night", "one-dark", "rose-pine",
#          "ayu-mirage", "everforest-dark", or any custom theme defined below
theme: dracula

# Icon set for file trees, PR views, and UI indicators
# Options: "nerd-font-v3", "text"
icon_set: nerd-font-v3

# Tiny PR/MR author avatar badges in the Info pane.
# Options: "auto" (Kitty-compatible terminals), "never", "always"
avatar_badges: auto

# Start with the filter focused and automatically select the first match when you press Enter
search_auto_select: false

# Maximum length for worktree names in the table display (0 disables truncation)
# Default: 95
max_name_length: 95

# ============================================================================
# DIFF & PAGER
# ============================================================================

# Maximum number of untracked files to show diffs for (0 disables diff display for untracked files)
max_untracked_diffs: 10

# Maximum characters to read from diff output (0 disables truncation)
max_diff_chars: 200000

# Diff formatter/pager used for rendering diffs (default: delta)
# Set to empty string ("") to disable diff formatting and use plain git diff output.
# Examples:
#   git_pager: delta
#   git_pager: diff-so-fancy
#   git_pager: ""         # disables formatting
#
# If git_pager is delta and git_pager_args is omitted, lazyworktree automatically
# selects a --syntax-theme matching the final UI theme, including CLI overrides.
git_pager: delta

# Extra arguments passed to git_pager.
# If you omit this setting and git_pager is delta, lazyworktree selects a syntax
# theme matching the final UI theme (e.g., Dracula for dark themes).
git_pager_args:
  - --syntax-theme
  - Dracula

# Set to true for interactive diff viewers that need terminal control (default: false)
# Interactive tools like diffnav (https://github.com/dlvhdr/diffnav), ftdv
# (https://terminaltrove.com/ftdv/), or tig require direct terminal access
# and
# cannot be piped through less. When true, only unstaged changes (git diff) are shown.
#
# Examples:
#   For interactive TUI diff navigators:
#     git_pager: diffnav
#     git_pager_interactive: true
#
#   For VS Code (uses git difftool for proper side-by-side comparison):
#     git_pager: code
#     # Opens one VS Code window per changed file via git difftool
#
git_pager_interactive: false

# Set to true for command-based diff viewers that run their own git commands (default: false)
# Tools like lumen (https://github.com/jnsahaj/lumen) invoke git internally and accept
# subcommands such as `lumen diff`, `lumen diff <commit>`, rather than reading piped input.
# When true, lazyworktree calls `<git_pager> diff [args...]` directly instead of piping
# git diff output through the pager.
#
# Examples:
#   git_pager: lumen
#   git_pager_command_mode: true
#
git_pager_command_mode: false

# Pager used for show_output custom commands
# Default: $PAGER environment variable or less if unset
pager: "less --use-color --wordwrap -swMQcR -P 'Press q to exit..'"

# Pager for CI check logs (v key on CI checks)
# When set, runs interactively with direct terminal control
# (no pipefail or environment adjustments like LESS=)
# Falls back to pager if not configured.
# ci_script_pager: "less -R"

# ============================================================================
# EDITOR
# ============================================================================

# Editor for opening files from the Status pane
# Default: $EDITOR environment variable, then nvim, then vi
editor: nvim

# ============================================================================
# COMMIT SCREEN
# ============================================================================

# Command run by Ctrl+O in the commit screen to generate a message from the
# staged diff. The diff is passed to the command on stdin.
#
# Expected output:
#   line 1 -> commit subject
#   line 2 -> blank separator
#   line 3+ -> commit body
#
# Example:
# commit:
#   auto_generate_command: 'aichat "Write a concise conventional commit message for this staged diff"'

# ============================================================================
# BRANCH NAMING
# ============================================================================

# Template for issue branch names when creating worktrees from issues
# Available placeholders:
#   {number} - The issue number
#   {title}  - The sanitised issue title (original)
#   {generated} - The AI-generated title (falls back to {title} if not available)
# Examples:
#   issue_branch_name_template: "issue-{number}-{title}"      # issue-123-fix-login-bug
#   issue_branch_name_template: "issue-{number}-{generated}"  # issue-123-fix-auth-bug (AI title)
#   issue_branch_name_template: "{number}-{title}"            # 123-fix-login-bug
issue_branch_name_template: "issue-{number}-{title}"

# Template for PR branch and worktree names when creating from pull requests
# Available placeholders:
#   {number} - The PR number
#   {title} - The sanitised PR title (original)
#   {generated} - The AI-generated title (falls back to {title} if not available)
#   {pr_author} - The PR author's username (sanitised)
# Examples:
#   pr_branch_name_template: "pr-{number}-{title}"             # pr-123-fix-login-bug
#   pr_branch_name_template: "pr-{number}-{generated}"         # pr-123-fix-auth-bug (AI title)
#   pr_branch_name_template: "pr-{number}-{pr_author}-{title}" # pr-123-alice-fix-login-bug
pr_branch_name_template: "pr-{number}-{title}"

# Script to generate branch name suggestions when creating worktrees from changes, issues, or PRs
#
# For issues/PRs: The script outputs a title that is used in the {generated} placeholder
#
# For diffs: The script outputs a complete branch name
#
# The script receives content on stdin (git diff for changes, issue/PR title+body for issues/PRs)
#
# Environment variables available to the script:
#   LAZYWORKTREE_TYPE: The type of creation (pr/issue/diff)
#   LAZYWORKTREE_NUMBER: The issue/PR number (empty for diff-based creation)
#   LAZYWORKTREE_TEMPLATE: The configured template (e.g., "pr-{number}-{title}")
#   LAZYWORKTREE_SUGGESTED_NAME: The template-generated name using original issue/PR title
#
# Examples:
#   # Simple title generation for issues/PRs
#   branch_name_script: "aichat -m gemini:gemini-2.5-flash-lite 'Generate a short title for this issue or PR. Output only the title.'"
#
#   # Different behaviour for diffs vs issues/PRs
#   branch_name_script: |
#     if [ "$LAZYWORKTREE_TYPE" = "diff" ]; then
#       aichat -m gemini:gemini-2.5-flash-lite 'Generate a complete branch name for this diff'
#     else
#       aichat -m gemini:gemini-2.5-flash-lite 'Generate a short title (no issue-/pr- prefix). Output only the title.'
#     fi
#
# branch_name_script: ""

# Script to generate an initial worktree note when creating from a PR/MR or issue
#
# The script receives content on stdin (title + body from the selected PR/MR or issue)
#
# Environment variables available to the script:
#   LAZYWORKTREE_TYPE: The source type (pr/issue)
#   LAZYWORKTREE_NUMBER: The PR/MR or issue number
#   LAZYWORKTREE_TITLE: The PR/MR or issue title
#   LAZYWORKTREE_URL: The PR/MR or issue URL
#
# If the script fails or outputs nothing, creation continues without writing a note.
#
# Example:
#   worktree_note_script: "aichat -m gemini:gemini-2.5-flash-lite 'Summarise this ticket as concise implementation notes.'"
#
# worktree_note_script: ""

# 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:
#   worktree_notes_path: ~/.local/share/lazyworktree/worktree-notes.json
#
# worktree_notes_path: ""

# Note storage type: "onejson" (default) or "splitted"
# When "splitted", each worktree note is stored as an individual markdown file
# with YAML frontmatter (icon, timestamp) and a markdown body.
# In this mode, worktree_notes_path is a path template with variables:
#   $REPO_OWNER     - repository owner (e.g. "myorg")
#   $REPO_REPONAME  - repository name (e.g. "myrepo")
#   $WORKTREE_NAME  - worktree directory basename
#   $REPO_NAME      - $REPOW_OWNER/$REPO_REPONAME
#
# Example:
#   worktree_note_type: splitted
#   worktree_notes_path: ~/notes/$REPO_NAME/$WORKTREE_NAME.md
#
# worktree_note_type: ""

# ============================================================================
# GIT OPERATIONS
# ============================================================================

# Merge method for the "Absorb worktree" action
# Options: "rebase" (rebases onto main, then fast-forwards main to the branch)
#          "merge" (creates a merge commit on main)
merge_method: "rebase"

# ============================================================================
# SECURITY
# ============================================================================

# Security setting for executing commands from .wt files
# Options: "tofu" (Trust On First Use - prompts you the first time or when commands change)
#          "never" (skips all commands from .wt files)
#          "always" (executes without prompting - use with caution)
trust_mode: "tofu"

# Debug log file path (for troubleshooting)
# When set, lazyworktree writes debug information to this file
# Leave commented out unless you're diagnosing issues
# debug_log: "/tmp/lazyworktree-debug.log"

# ============================================================================
# LIFECYCLE HOOKS
# ============================================================================
#
# Environment variables available to init_commands, terminate_commands, and custom_commands:
#   WORKTREE_PATH       - Path to the worktree
#   WORKTREE_BRANCH     - Name of the git branch
#   WORKTREE_NAME       - Name of the worktree (directory basename)
#   MAIN_WORKTREE_PATH  - Path to the main repository
#   REPO_NAME           - Repository key (from GitHub/GitLab or local hash)
#   REPO_OWNER          - Repository owner when available
#   REPO_REPONAME       - Repository name without the owner
#   LAZYWORKTREE_TYPE   - Source context: pr, issue, or diff when known
#   LAZYWORKTREE_NUMBER - PR/MR or issue number when known
#   LAZYWORKTREE_TITLE  - PR/MR or issue title when known
#   LAZYWORKTREE_URL    - PR/MR or issue URL when known
#   LAZYWORKTREE_DESCRIPTION - PR/MR or issue body when known
# Contextual LAZYWORKTREE_* values are empty when no source context is known.

# 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
#
# Security: Commands from .wt files require trust confirmation (see trust_mode setting)
#
# Examples:
#   - link_topsymlinks                                    # Symlink config files
#   - cp $MAIN_WORKTREE_PATH/.env $WORKTREE_PATH/.env   # Copy environment
#   - npm install                                         # Install dependencies
init_commands:
  - link_topsymlinks

# 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: Same as init_commands (see above)
# Security: Commands from .wt files require trust confirmation (see trust_mode setting)
#
# Examples:
#   - echo "Cleaning up $WORKTREE_NAME"        # Log cleanup
#   - rm -rf $WORKTREE_PATH/tmp/*              # Remove temporary files
terminate_commands:
  - echo "Cleaning up $WORKTREE_NAME"

# ============================================================================
# CUSTOM COMMANDS
# ============================================================================

# Custom commands are organised by pane context. Use "universal" for commands
# available in all panes, or a pane name for context-specific bindings.
#
# Pane names: universal, worktrees, info, status, log, notes, agent_sessions
#
# Commands are executed interactively (TUI suspends, similar to lazygit).
# Pane-specific bindings take precedence over universal ones when the same
# key is defined in both.
#
# Environment variables: Same as lifecycle hooks (see above)
#
# Supported key formats:
#   - Single keys: e, s, t, l
#   - Modifier combinations: "ctrl+e", "alt+t", "ctrl+shift+s"
#   - Special keys: enter, esc, tab, space
#
# Fields:
#   command: The command to execute (required)
#   description: Description shown in help screen (optional)
#   show_help: Show in help screen and footer hints (default: false)
#   wait: Wait for keypress after command completes (default: false, useful for quick commands)
#   show_output: Display command output in the pager instead of running interactively (default: false)
#
# Prefix a key with "_" to make it command-palette only (no direct keybinding):
#   _review:
#     command: "make review"
#     description: "Review current worktree"
#
# Container execution: run commands inside OCI containers (docker/podman).
# The container runtime is auto-detected (podman preferred, then docker).
# The worktree path is automatically mounted to /workspace.
#
# Container fields:
#   image: Container image (required, e.g. "golang:1.22")
#   runtime: Override runtime binary (optional, auto-detect if empty)
#   mounts: Additional bind mounts (optional)
#     - source: Host path
#       target: Container path
#       read_only: true/false (default: false)
#       options: Comma-separated volume options (e.g. "z" for SELinux relabeling)
#   env: Extra environment variables (optional)
#   working_dir: Working directory inside container (default: /workspace)
#   extra_args: Additional docker/podman run arguments (optional)
#   args: Arguments passed after the image as CMD (optional)
#   interactive: Allocate TTY for interactive use (default: false).
#
# Container example:
#
#   custom_commands:
#     universal:
#       ctrl+g:
#         command: "go test ./..."
#         description: "Run tests in container"
#         show_output: true
#         container:
#           image: "golang:1.22"
#
custom_commands:
  universal:
    s:
      command: zsh
      description: Open shell
      show_help: true
    "ctrl+t":
      command: "git status -sb"
      description: Status
      show_help: true
      show_output: true
    "T":
      description: Tmux session
      show_help: true
      tmux:
        session_name: "wt:$WORKTREE_NAME"
        attach: true
        on_exists: "switch"
        windows:
          - name: claude
            command: claude
          - name: shell
            command: zsh
          - name: lazygit
            command: lazygit
    "Z":
      description: Zellij session
      show_help: true
      zellij:
        session_name: "wt:$WORKTREE_NAME"
        attach: true
        on_exists: "switch"
        windows:
          - name: claude
            command: claude
          - name: shell
            command: zsh
          - name: lazygit
            command: lazygit
    _review:
      command: "make review"
      description: "Review current worktree"
  worktrees:
    t:
      command: make test
      description: Run tests
      show_help: false
      wait: true
    l:
      command: ls -la
      description: List files
      show_help: true
      wait: true
  status:
    e:
      command: "${EDITOR:-nvim} $FILE_PATH"
      description: Edit file in editor
      show_help: true

# ============================================================================
# KEYBINDINGS
# ============================================================================

# Bind any key to a built-in palette action, organised by pane context.
# Use "universal" for bindings active in all panes, or a pane name for
# context-specific bindings. Pane-specific bindings take precedence over universal.
#
# Pane names: universal, worktrees, info, status, log, notes, agent_sessions
#
# Use any action ID listed in docs/action-ids.md (e.g. git-lazygit, worktree-delete, git-diff).
# Supported key formats: same as custom_commands (e.g. "G", "ctrl+d", "alt+l")
#
# Examples:
# keybindings:
#   universal:
#     G: git-lazygit
#     F: git-fetch
#   worktrees:
#     x: worktree-delete
#   log:
#     d: git-diff

# ============================================================================
# CUSTOM MENUS
# ============================================================================

# Custom items for the worktree creation menu (triggered by 'c' key)
# Each item runs an external command that outputs a branch name
# Workflow: select base branch first, then command runs, then you enter/confirm the branch name
#
# Non-interactive commands run with a 30-second timeout
# Output (first line, whitespace trimmed, case preserved) is used as the suggested name
#
# Fields:
#   label: Display label shown in the menu (required)
#   description: Help text shown next to the label (optional)
#   command: Shell command that outputs a branch name on stdout (required)
#   interactive: Run interactively (default: false). Set to true for TUI-based
#                commands like fzf or jayrah. Suspends lazyworktree, runs the
#                command in the terminal, and captures stdout via temp file
#   post_command: Command to run in new worktree after creation (optional)
#                 Runs after global/repo init_commands. Has access to environment
#                 variables like WORKTREE_BRANCH, WORKTREE_PATH, LAZYWORKTREE_*, etc.
#                 The pre-create command receives MAIN_WORKTREE_PATH and REPO_*,
#                 with WORKTREE_* and LAZYWORKTREE_* set to empty values.
#   post_interactive: Run post-command interactively (default: false). When true,
#                     TUI suspends to show command I/O
custom_create_menus:
  - label: "From JIRA ticket"
    description: "Create from JIRA issue"
    command: "jayrah browse 'SRVKP' --choose"
    interactive: true
    post_command: "echo ${WORKTREE_BRANCH}|sed 's/[^a-zA-Z0-9._-]/-/g' > $WORKTREE_PATH/.branchname;echo 'Branch name saved to .branchname'"
    post_interactive: false
  - label: "From clipboard"
    description: "Use clipboard as branch name"
    command: "pbpaste"

# ============================================================================
# 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.
#
# Two ways to define a custom theme:
#
# 1. Inherit from a built-in theme and override specific colours:
#    custom_themes:
#      my-dark:
#        base: dracula
#        accent: "#FF6B9D"
#        text_fg: "#E8E8E8"
#
# 2. Define a complete theme without a base (all 11 colour fields required):
#    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"
#
# Custom themes can also inherit from other custom themes:
#    custom_themes:
#      base-custom:
#        base: dracula
#        accent: "#FF0000"
#      derived:
#        base: base-custom
#        accent: "#00FF00"
#
# Available colour fields (snake_case in YAML):
#   - accent: Primary accent colour (used for highlights, selected items)
#   - accent_fg: Foreground colour for text on accent background
#   - accent_dim: Dimmed accent colour (used for selected rows/panels)
#   - border: Border colour
#   - border_dim: Dimmed border colour
#   - muted_fg: Muted text colour (for less important text)
#   - text_fg: Primary text colour
#   - success_fg: Success/positive indicator colour
#   - warn_fg: Warning indicator colour
#   - error_fg: Error indicator colour
#   - cyan: Cyan accent colour
#
# Colour values must be in hex format: #RRGGBB or #RGB
# When using a base theme, only specify colours you want to override.
# When not using a base, all 11 colour fields are required.
#
# custom_themes:
#   my-dark:
#     base: dracula
#     accent: "#FF6B9D"
#   my-light:
#     base: dracula-light
#     accent: "#0066CC"