---
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

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

### Clone and start working

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

### Create feature branch

From inside any worktree:

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

### Switch between branches

Just `cd` to the worktree directory—no checkout needed:

```bash
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

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

### Convert existing repo

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

## Command Details

- **New project**: See [refs/new-project.md](refs/new-project.md) for remote templates
- **Cloning**: See [refs/cloning.md](refs/cloning.md) for remote configuration and own vs contributor mode
- **Adding worktrees**: See [refs/adding.md](refs/adding.md) for hooks and branch creation
- **Converting repos**: See [refs/converting.md](refs/converting.md) for `wt init` details
- **Config files**: See [refs/config.md](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

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

---

See [refs/installation.md](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.