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

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