Lazyworktree

LazyWorktree is a terminal-based Git worktree management tool designed to create, switch, and remove worktrees without leaving your editor context. It provides a keyboard-first UX for managing multiple simultaneous checkouts of the same repository.

Core Capabilities

• Worktree Management: Create, rename, remove, absorb, and prune worktrees. Switch between them without the churn of traditional branch checkouts.
• Development Workflow: Perform Git operations (stage, unstage, commit, diff) in-terminal. View CI checks and logs from GitHub/GitLab. Open PR/MR links directly.
• Container Integration: Run commands inside OCI containers (Docker/Podman) with automatic worktree mounting for isolated, reproducible builds.
• Customisation: Configure settings globally, per repository, or via CLI overrides. Add custom command bindings for shell, tmux, or zellij.

The command palette surfaces several categories of built-in workflows:

• Worktree actions: create, delete, rename, set icon, set colour, absorb, prune, and sync.
• Commit flow: Search for Open commit screen to open the staged commit modal.
• Git operations: Access lazygit, cherry-pick, and diff viewing.
• Navigation and pane controls: focus pane, toggle zoom, and switch layout.
• Settings: Perform theme selection with live preview.

When using multiplexers like tmux or zellij, be aware of the following:

• Session Name Sanitisation: Session names are sanitised to remove invalid characters. If your worktree path contains special characters, the resulting session name may differ from the path.
• Existing Session Behavior: Controlled by the on_exists configuration:
  • attach: (Default) Attach to the existing session.
  • replace: Close the existing session and create a new one.
  • ignore: Do nothing.
• CLI exec Limitations: The new-tab command is not supported in CLI exec mode because it requires a running multiplexer session (available only in the TUI). Use shell or command types for CLI-based commands.

LazyWorktree uses a Trust On First Use (TOFU) model for executing .wt files. Key implications include:

• trust_mode: never: This setting blocks all .wt command execution. Init and terminate hooks will never run.
• File Modifications: In tofu mode, any change to a .wt file (including whitespace) changes its hash. This invalidates the stored trust and triggers a re-approval prompt to prevent silent execution of modified commands.
• Storage: Trust decisions are stored per-file in ~/.local/share/lazyworktree/trusted.json, keyed by the file content hash. Deleting this file resets all trust decisions.
• Team Workflows: Trust decisions are local. If a team modifies a .wt file, every developer will be prompted to re-approve the new hash independently.

Lazyworktree applies specific rules to ensure branch names are Git-compatible and safe for directory names:

Sanitization Rules:

• Special characters are converted to hyphens (-).
• Leading and trailing hyphens are removed.
• Consecutive hyphens are collapsed into a single hyphen.
• Length is capped at 50 characters for manual names and 100 characters for automatically generated names.

Suggested Names: If you do not provide an explicit name when creating a worktree, the tool pre-fills the prompt with a random adjective-noun suggestion (e.g., scrupulous-stable, heedful-foxglove). These are generated from a pool of over 58,000 pairings and are guaranteed to be lowercase ASCII without punctuation.

LazyWorktree uses a layered configuration model. If a setting is defined in multiple places, the source with the highest precedence wins. The order from highest to lowest precedence is:

1. CLI overrides: Using the --config flag.
2. Git local configuration: Settings stored in the current repository via git config --local.
3. Git global configuration: Settings stored globally via git config --global.
4. YAML file: The primary configuration file located at ~/.config/lazyworktree/config.yaml.
5. Built-in defaults: The fallback values used if no other configuration is provided.

LazyWorktree uses a layered configuration model. Settings are applied in the following order of precedence (later stages override earlier ones):

1. Built-in defaults: Provided by DefaultConfig().
2. YAML configuration: Loaded from the standard config location or an explicit file provided via the --config flag.
3. Git global config: Settings defined via git config --global lw.*.
4. Git local config: Settings defined via git config --local lw.* for the current repository.
5. Runtime CLI overrides: Flags passed during execution via bootstrap.

Note: There is no LAZYWORKTREE_* environment variable configuration cascade. Repository lifecycle hooks are loaded from .wt files rather than a repo-local YAML app config.

Lazyworktree allows you to persist notes for your worktrees. You can choose between two storage modes via worktree_note_type:

1. onejson (default): All notes are stored in a single shared JSON file defined by worktree_notes_path. This is ideal for cross-system synchronization as keys are relative to the repo/worktree.
2. splitted: Each worktree gets its own individual markdown file. In this mode, worktree_notes_path acts as a template using the following variables:
   • $REPO_OWNER
   • $REPO_REPONAME
   • $WORKTREE_NAME

worktree_note_type: "splitted"
worktree_notes_path: "~/notes/$REPO_OWNER/$REPO_REPONAME/$WORKTREE_NAME/note.md"