Skip to main content
Get up and running with LazyWorktree quickly. This guide walks you through your first worktree operations.

​
Prerequisites

Before starting, ensure you have:
  • Git 2.31 or later installed
  • A Git repository to work with
  • LazyWorktree installed (see Installation)
For PR/MR integration features, you’ll also need gh (GitHub CLI) or glab (GitLab CLI) installed.

​
Launch LazyWorktree

1

Navigate to your repository

Open your terminal and navigate to any Git repository:
cd /path/to/your/git/repository
2

Run LazyWorktree

Launch the TUI by running:
lazyworktree
You’ll see the main interface with your worktrees listed (if any exist).
3

View help

Press ? to view the interactive help screen with all available key bindings.Press q or Esc to close the help screen.

​
Create your first worktree

1

Press 'c' to create

Press the c key to open the worktree creation menu.
2

Choose creation method

Select from several creation options:
  • From current branch - Copy your current branch to a new worktree
  • From branch - Create from an existing branch or new branch name
  • From PR/MR - Create from a GitHub/GitLab pull/merge request
  • From issue - Create from a GitHub/GitLab issue with auto-generated branch name
3

Enter worktree name

Type the name for your new worktree (or accept the auto-generated name).LazyWorktree will automatically sanitise special characters to be Git-compatible.
4

Wait for creation

LazyWorktree creates the worktree in your configured directory (default: ~/.local/share/worktrees/<org>-<repo>).The new worktree appears in the list immediately.
There are two ways to jump into a worktree:

​
Method 1: Direct output

  1. Select a worktree with j/k (or arrow keys)
  2. Press Enter - LazyWorktree outputs the path and exits
  3. Use this with your shell:
cd $(lazyworktree)
For a better experience, set up shell integration to automatically change directories:
zsh
# Add to ~/.zshrc
lwcd() {
  local selected_path=$(lazyworktree)
  if [[ -n "$selected_path" ]]; then
    cd "$selected_path"
  fi
}
Then use: 
lwcd  # Select and jump to worktree
See Shell Integration for more advanced setups.

​
Common operations

​
View worktree information

  • Focus on a worktree to see details in the Status pane (right side)
  • View linked PR/MR information
  • Check CI status (if GitHub Actions or GitLab CI configured)
  • See branch divergence from upstream

​
Rename a worktree

  1. Select the worktree
  2. Press m (rename)
  3. Enter the new name
  4. The branch is renamed too if the directory name matches the branch name

​
Delete a worktree

  1. Select the worktree
  2. Press D (delete)
  3. Confirm the deletion
  4. Both the worktree directory and branch are removed
Deletion is permanent! Make sure you’ve committed or pushed any important changes.

​
Explore more features

Now that you’ve mastered the basics, explore these powerful features:

Key Bindings

Complete reference of all keyboard shortcuts

Creation Modes

Advanced worktree creation from PRs, issues, and more

PR/MR Integration

Link worktrees with GitHub and GitLab pull requests

Custom Commands

Set up tmux/zellij sessions and custom workflows

​
Quick reference

Essential key bindings to remember:
KeyAction
?Show help
cCreate worktree
EnterJump to worktree (outputs path)
mRename worktree
DDelete worktree
rRefresh list
qQuit
1-5Focus pane (1=Worktrees, 2=Status, 3=Git Status, 4=Commits, 5=Notes)
See the complete keybindings reference for all available shortcuts.

​
Next steps

1

Configure your setup

Customise LazyWorktree with your preferred theme, layout, and behaviour.See Configuration
2

Set up shell integration

Install shell functions for seamless directory navigation.See Shell Integration
3

Explore advanced features

Learn about notes, taskboards, CI status tracking, and custom commands.See Core Features

Build docs developers (and LLMs) love

Get started for freeTalk to us