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. If you need to clone and whether to use worktrees/this skill is unclear, ask the user. compatibility: Requires wt CLI, git, and gum license: GPL-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