1---
2name: managing-and-navigating-worktrees
3description: 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.
4compatibility: Requires wt CLI, git, and gum
5license: AGPL-3.0-or-later
6metadata:
7 author: Amolith <amolith@secluded.site>
8---
9
10# Managing Git Worktrees with wt
11
12`wt` manages git repositories using a bare repository structure:
13
14- `.bare/` contains the actual git repository
15- `.git` is a file pointing to `.bare/`
16- Each branch lives in its own directory as sibling worktrees
17
18## Quick Reference
19
20| Command | Purpose |
21| --------------- | --------------------------------------- |
22| `wt c <url>` | Clone repo into bare structure |
23| `wt n <name>` | Create new project |
24| `wt a <branch>` | Add worktree for branch |
25| `wt r <branch>` | Remove worktree |
26| `wt l` | List worktrees with status |
27| `wt f` | Fetch all remotes |
28| `wt init` | Convert existing repo to bare structure |
29
30## Common Workflows
31
32### Start a new project
33
34```bash
35wt n my-project --remote github
36cd my-project/main
37```
38
39### Clone and start working
40
41```bash
42wt c https://github.com/user/repo.git
43cd repo/main
44```
45
46### Create feature branch
47
48From inside any worktree:
49
50```bash
51wt a feature/new-thing -b main
52cd ../feature/new-thing
53```
54
55### Switch between branches
56
57Just `cd` to the worktree directory—no checkout needed:
58
59```bash
60cd ../main # switch to main
61cd ../feature/x # switch to feature branch
62```
63
64If the branch already exists in a remote, but doesn't yet have a local worktree, use `wt a branch` to fetch and create it.
65
66### Clean up finished work
67
68```bash
69wt r feature/old -b # remove worktree AND delete branch
70```
71
72### Convert existing repo
73
74```bash
75cd existing-repo
76wt init # --dry-run to preview, -y to skip prompt
77```
78
79## Command Details
80
81- **New project**: See [refs/new-project.md](refs/new-project.md) for remote templates
82- **Cloning**: See [refs/cloning.md](refs/cloning.md) for remote configuration and own vs contributor mode
83- **Adding worktrees**: See [refs/adding.md](refs/adding.md) for hooks and branch creation
84- **Converting repos**: See [refs/converting.md](refs/converting.md) for `wt init` details
85- **Config files**: See [refs/config.md](refs/config.md) for `.wt.lua` and global config
86
87If 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.
88
89## Working Directory
90
91`wt` works from either the project root or any worktree. Run `wt l` to determine context:
92
93- **In a worktree**: Current worktree shows `./` in the Path column
94- **At project root**: All paths are relative names (e.g., `main`, `feature/foo`)
95
96From project root, `wt a` skips hooks. From a worktree, hooks trigger.
97
98## Key Behaviors
99
1001. **Hooks only trigger from worktrees**: Running `wt a` from project root skips hooks
1012. **Branch paths**: `feature/foo` becomes `project/feature/foo` (nested) or `project_feature_foo` (flat, if configured)
102
103---
104
105See [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.