# Try Git worktrees first

A small exercise with two folders and one text file. No agents involved.

Run commands one at a time. Stop on an error. Commands run in a terminal; the two greeting lines are file content for your editor.

Step 1

## Start with one folder

You need Git, a terminal and a plain-text editor. Check git --version first. No Node.js, coding agent or account is needed. Open a terminal in a parent folder where you want to keep this exercise. Use a fresh location if worktree-primer or worktree-greeting already exists.

```
git init -b main worktree-primer
cd worktree-primer
```

In your editor, create hello.txt inside worktree-primer. Put exactly this one line in it, then save as plain text (not hello.txt.txt):

```
Hello from main.
```

Back in the terminal, save the file in Git history:

```
git add hello.txt
git commit -m "Add greeting"
```

You should see a commit containing hello.txt. The main branch now points to that commit. If Git asks who you are, set git config user.name "Your Name" and git config user.email "your-email" with your own values, then retry the failed commit. These settings apply only to this repository.

Step 2

## Create a second working folder

```
git worktree add -b greeting ../worktree-greeting
git worktree list
```

You should see two paths: worktree-primer on main, and worktree-greeting on greeting. The -b option creates the greeting branch; ../worktree-greeting names a sibling folder. Both branches begin at the same commit.

A branch tracks a line of development. A worktree is a working folder for a checkout. Worktrees share one Git repository, including its object database and branch references. Each has its own working files, staging area (index) and HEAD, which identifies its current checkout. Creating a branch alone does not create another folder. A worktree can also check out a commit directly, with a detached HEAD.

Step 3

## Change only the second copy

```
cd ../worktree-greeting
git branch --show-current
```

The branch check should print greeting. Open worktree-greeting/hello.txt in your editor. Replace its line with the following and save:

```
Hello from a worktree.
```

Inspect and commit the change from that folder:

```
git diff
git add hello.txt
git commit -m "Update greeting"
```

You should see a one-line change and a new commit. Now return to the original folder and compare the two committed versions:

```
cd ../worktree-primer
git branch --show-current
git show HEAD:hello.txt
git show greeting:hello.txt
```

You should see main, then Hello from main., then Hello from a worktree. The original file stayed unchanged. The original folder can still read the greeting commit because the worktrees share history. git show reads a committed version; it does not switch branches.

Step 4

## Bring the change into main

Stay in worktree-primer, on main. Review the difference, then merge:

```
git diff main...greeting
git merge --ff-only greeting
git show HEAD:hello.txt
git log --oneline --all --decorate -3
```

You should see a fast-forward merge and Hello from a worktree. in the original folder. The log shows main and greeting pointing to the updated commit. This example has no competing edits, so Git can move main forward. --ff-only stops instead of creating a merge commit if the branches have diverged. Worktrees do not merge changes for you; you chose when to integrate them.

Step 5

## Remove the extra folder

Stay in worktree-primer. The change is committed and merged. Before removing the extra folder, run git -C ../worktree-greeting status --short --ignored and preserve any local files you need. Removal also deletes ignored files. Then remove the clean worktree:

```
git worktree remove ../worktree-greeting
git worktree list
git branch --list
```

You should see only the original worktree in the worktree list. The branch list still includes greeting: removing its working folder does not delete its branch or the shared history. Keep the original repository if you want to explore.

If Git refuses removal because files are uncommitted, inspect git -C ../worktree-greeting status and save any work you want to keep. Do not force removal. To resume later, use git worktree list and continue from the right folder rather than repeating setup.

## Put it to work with two agents

Separate working folders give coding agents separate checkouts. You still review, merge and test their changes. Worktrees do not restrict what programs can access on your computer.

Continue at https://worktrees.md/learn. The agent lab starts with its own downloaded taskboard repository. Keep it separate from this primer.