Git worktrees - Lesson 2 of 5
Create one task, one branch, one directory
A worktree earns its keep when a task has its own branch and obvious path. The main checkout stays available for review, tests, or the next integration.
Use an explicit creation pattern
From the repository's main checkout, start a new branch and linked directory together:
git switch main
git pull --ff-only
git worktree add -b docs/readme-refresh ../repo-readme-refreshThe branch name expresses the change. The sibling directory expresses the location. Git starts the new branch at the current HEAD unless you name another starting point.
Why refresh first: a new task should begin from the intended base. The command is not a replacement for your repository's branch or review policy.
Choose the right form
| Intent | Command | Result |
|---|---|---|
| New task branch | git worktree add -b fix/login ../repo-login | New branch and linked checkout. |
| Existing branch | git worktree add ../repo-review review/123 | Existing branch in a new checkout, if free. |
| Throwaway test | git worktree add --detach ../repo-scratch | Detached checkout with no task branch. |
| Temporary remote location | git worktree add --lock --reason "external disk" ../repo-archive archive | Linked checkout protected from automatic pruning. |
Verify the starting point
cd ../repo-readme-refresh
git status --short
git branch --show-current
git log --oneline --decorate -3
git worktree list --verboseA clean status and the intended branch are the minimum before editing. If Git says the branch is already checked out elsewhere, do not force it. Find the other path or create a new branch for this task.
Retrieval check
Primary reading
- git-worktree - read
add,-b,--detach, and--lock.
Ask follow-up questions: Ask the agent to turn your repository's actual task naming and base-branch convention into one safe creation command.