yawn — Yet Another Worktree Navigator

A CLI tool for managing git worktrees and discovering projects.

Install

From source

cargo install git-yawn

Nix flake

inputs.yawn.url = "github:ComeBertrand/yawn";

# then in your packages:
inputs.yawn.packages.${system}.default

GitHub Releases

Download a binary from the releases page, or use the shell installer:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/ComeBertrand/yawn/releases/latest/download/yawn-installer.sh | sh

Usage

yawn list [path] [--pretty]     Discover git projects under a directory
yawn resolve <pretty-name>      Map a pretty name back to an absolute path
yawn open <path>                Open a terminal in the given directory
yawn create <name> [--source <base>] [--open]   Create a git worktree
yawn delete <name>              Remove a worktree

Discover projects

# List all git projects under ~/projects
yawn list ~/projects

# Human-readable output with worktree annotations
yawn list ~/projects -p

Pretty output example:

my-app
fix-branch [worktree of my-app]
dotfiles
notes (personal)
notes (work)

List worktrees

When run inside a git repo without a path, yawn list shows the worktrees of the current project:

cd ~/projects/my-app
yawn list

/home/user/projects/my-app
/home/user/worktrees/my-app--fix-branch
/home/user/worktrees/my-app--feature-x

Interactive project switcher

Combine with a fuzzy finder like rofi or fzf:

# rofi
yawn open "$(yawn resolve "$(yawn list ~ --pretty | rofi -dmenu -p project -i)")"

# fzf
yawn open "$(yawn resolve "$(yawn list ~ --pretty | fzf)")"

Worktrees

Worktrees are created under a configurable root directory (default: ~/worktrees) using the naming convention <project>--<name>. For example, running yawn create feature-x from inside a repo called my-app creates:

~/worktrees/my-app--feature-x

When listing with --pretty, the <project>-- prefix is stripped and the worktree is annotated:

feature-x [worktree of my-app]

Branch resolution when creating a worktree follows this order:

1. If <name> exists as a local branch, check it out.
2. If <name> exists as origin/<name>, track it.
3. If --source <base> is provided, create a new branch from <base>.
4. Otherwise, create a new branch from the default branch (origin/HEAD, falling back to main then master).

If a .yawninclude file exists in the main repo root, the files it lists are copied into the new worktree. This is useful for local config files like .env that aren't tracked by git. Glob patterns are supported.

# .yawninclude
.env
.env.local
config/*.toml
data_*.csv

# Create a worktree (new branch from default branch)
yawn create feature-x

# Create from a specific base branch
yawn create feature-x --source develop

# Create and immediately open a terminal in it
yawn create feature-x --open

# Delete a worktree
yawn delete feature-x

Configuration

~/.config/yawn/config.toml — all fields are optional.

[discovery]

[session]

[worktree]

Example

[discovery]
max_depth = 3
ignore = [".*", "node_modules", "target", "vendor"]

[session]
open_command = "kitty --directory {dir} --title 'dev: {name}'"

[worktree]
root = "~/worktrees"

Shell Completion

Bash

Copy completions/yawn.bash to your bash-completion directory:

cp completions/yawn.bash ~/.local/share/bash-completion/completions/yawn

License

MIT