name: managing-and-navigating-worktrees description: Manages git worktrees and repos using the wt CLI. Use when cloning or creating new repos, adding worktrees, switching branches or branches, when the user mentions wt or worktrees. compatibility: Requires wt CLI, git, and gum license: AGPL-3.0-or-later metadata: author: Amolith amolith@secluded.site

Managing Git Worktrees with wt

wt manages git repositories using a bare repository structure:

.bare/ contains the actual git repository
.git is a file pointing to .bare/
Each branch lives in its own directory as sibling worktrees

Quick Reference

Command	Purpose
`wt c <url>`	Clone repo into bare structure
`wt n <name>`	Create new project
`wt a <branch>`	Add worktree for branch
`wt r <branch>`	Remove worktree
`wt l`	List worktrees with status
`wt f`	Fetch all remotes
`wt init`	Convert existing repo to bare structure

Common Workflows

Start a new project

wt n my-project --remote github
cd my-project/main

Clone and start working

wt c https://github.com/user/repo.git
cd repo/main

Create feature branch

From inside any worktree:

wt a feature/new-thing -b main
cd ../feature/new-thing

Switch between branches

Just cd to the worktree directory—no checkout needed:

cd ../main        # switch to main
cd ../feature/x   # switch to feature branch

If the branch already exists in a remote, but doesn't yet have a local worktree, use wt a branch to fetch and create it.

Clean up finished work

wt r feature/old -b    # remove worktree AND delete branch

Convert existing repo

cd existing-repo
wt init              # --dry-run to preview, -y to skip prompt

Command Details

New project: See refs/new-project.md for remote templates
Cloning: See refs/cloning.md for remote configuration and own vs contributor mode
Adding worktrees: See refs/adding.md for hooks and branch creation
Converting repos: See refs/converting.md for wt init details
Config files: See refs/config.md for .wt.lua and global config

If you lack context, READ THESE instead of immediately trying to use wt or relying on -h output. The refs might just give you the answer without you needing to fumble and find them.

Working Directory

wt works from either the project root or any worktree. Run wt l to determine context:

In a worktree: Current worktree shows ./ in the Path column
At project root: All paths are relative names (e.g., main, feature/foo)

From project root, wt a skips hooks. From a worktree, hooks trigger.

Key Behaviors

Hooks only trigger from worktrees: Running wt a from project root skips hooks
Branch paths: feature/foo becomes project/feature/foo (nested) or project_feature_foo (flat, if configured)

See refs/installation.md if you try to use wt and it's not available. Do not reference this file until and unless you invoke wt and get some kind of command not found error.

SKILL.md