I used to think Git worktrees were an advanced feature for “serious” Git people.

Then I hit the same situation over and over:

• I’m in the middle of one change
• a small hotfix pops up
• or I need to review another branch quickly
• and I don’t want to stash/unstash my way through it

Worktrees turned out to be the cleanest answer.

The second realization was more practical:

if you can manage worktrees from your phone, you stop blocking on “I’ll do it later when I’m back at my desk.”

This guide is a calm, repeatable workflow for worktrees — with a phone-first control surface.

Quick definition: what a worktree is (in plain language)

A Git repository normally has one working directory (your checked-out files).

A worktree lets one repo have multiple working directories, so you can check out more than one branch at a time.

Git’s own docs describe it as managing “multiple working trees attached to the same repository”, letting you check out more than one branch at a time. (Source: https://git-scm.com/docs/git-worktree)

Practically:

• the repo’s object database is shared
• each worktree gets its own checked out files + index/HEAD state

That’s why worktrees feel much lighter than “clone the repo twice”.

What I tried first (and why I moved on)

When a hotfix interrupts a bigger change, the usual options are:

• stash: works, but it’s easy to forget what you stashed and why
• commit a WIP: works, but it pollutes history and invites mistakes
• clone again: works, but it’s slow and duplicates a lot

Worktrees let me keep the main branch clean and keep momentum.

A workflow that worked for me

I ended up using a “remote UI over my computer” approach for day-to-day Git control.

Happier is one option that supports that approach.

In Happier, you can add a repo folder as a Project, then use Source control + Files outside of sessions.

Trade-off: your computer still has to be online.

If you’re new to Happier (what it is, and where to get it)

If you haven’t seen Happier before: it’s an open-source companion app (mobile/web/desktop) that lets you keep workflows on a computer you trust, then manage them from your phone.

Get set up:

• GitHub: https://github.com/happier-dev/happier
• Install/download: https://github.com/happier-dev/happier#how-it-works
• Discord: https://discord.gg/W6Pb8KuHfg

The mental model that prevents mistakes

Before you touch worktrees from a phone, adopt two rules:

1. One worktree = one intent. If the hotfix is unrelated, it deserves its own worktree.

2. Small edits from phone; deep surgery from keyboard. Your phone is great for review, light changes, and pushing a narrow fix.

Step-by-step: manage worktrees from your phone

1) Add the repo as a Project

1. Open Projects.
2. Tap ADD A PROJECT.
3. Tap Choose a folder on your computer.
4. In Select Path, navigate to the repo folder.
5. Tap Use.

2) Use Source control as your “safety surface”

Inside the Project:

• open Source control
• start on Changed files

This gives you a clean way to:

• review what’s dirty
• commit intentionally
• sync (Pull/Push)

If you see:

• Operation requires a clean working tree.

…treat it as a guardrail.

3) Create a new worktree (hotfix)

There are two ways to think about creating a worktree:

• “I want a new directory for a new branch”
• “I want a new directory for an existing branch”

In raw Git, that’s essentially:

• git worktree add <path> (new branch convenience)
• or git worktree add <path> <branch> (existing branch)

(Source: https://git-scm.com/docs/git-worktree)

In Happier Projects, the key is the outcome:

• a second working directory you can open as its own Project
• without disturbing whatever was already checked out

4) Keep phone edits narrow

Once the worktree exists, my phone loop is:

1. open the worktree Project
2. use Files to search the exact file
3. make the smallest edit
4. Save
5. switch to Source control → Changed files → ↓ Review
6. commit a small change

5) Push the hotfix (and stop)

Once the hotfix is pushed, I try to stop.

The value of worktrees is that the hotfix doesn’t expand into a second full project.

It stays narrow.

6) Clean up worktrees (so they don’t become clutter)

Worktrees are powerful, but they can accumulate.

My rule:

• if the branch is merged, remove the worktree
• if it’s long-running, keep it but name it clearly

In raw Git, stale administrative files can be cleaned up with git worktree prune if a worktree was deleted incorrectly. (Source: https://git-scm.com/docs/git-worktree)

In a UI-first workflow, the goal is simpler: don’t leave a pile of abandoned working directories.

Worktrees + multiple agents (why this started to matter)

Worktrees have been around for a while, but they started to click for me once I began running more than one agent/session in parallel.

If you’re using Claude Code, Codex, or OpenCode, the basic multi-agent pattern looks like this:

• one worktree per task
• one session per worktree

That gives you isolation:

• agents don’t step on each other’s files
• diffs stay easier to review
• commits stay narrower

In Happier, you can do this without turning your phone into a terminal:

• create/add a worktree
• open it as a Project
• launch a new session in that worktree (Claude/Codex/OpenCode)
• monitor sessions from the same app where you also review diffs, commits, and history

I’m intentionally not treating this as “run 10 agents at once.”

It’s: run 2–3 in parallel, and keep them isolated so review stays sane.

Terminal (optional)

In Projects, you also have a fully-featured terminal accessible on the terminal icon in the project page header (on the right).

I treat terminal as the escape hatch for:

• the one command the UI doesn’t expose
• sanity checks
• worktree cleanup when something is in a strange state

If you find yourself doing everything in terminal, it’s a signal to either:

• simplify the workflow, or
• wait for a keyboard

FAQ (real worktree questions)

What’s the difference between a branch and a worktree?

A branch is a pointer (a name for a line of commits).

A worktree is a separate working directory where you can check out a branch.

You typically use both together: one branch per worktree.

Why use worktrees instead of stashing?

Stashing is great for quick context switches.

Worktrees are great when the interruption is real work (a hotfix, a review, a test run) and you want zero chance of stepping on your current changes.

Can I have the same branch checked out in two worktrees?

By default, Git prevents checking out the same branch in two worktrees at once.

That’s a safety feature.

(You can do detached HEAD worktrees for “just run tests” style work without a branch.)

How do I name worktrees so future-me understands them?

Use names that encode intent:

• hotfix-<ticket>
• review-<pr>
• release-<version>

What’s the biggest way worktrees go wrong?

Not the Git part.

The human part:

• forgetting which worktree is “the one with unpushed changes”
• leaving half-finished hotfix worktrees around

The fix is simple: keep worktrees narrow and clean them up.

When should I not use worktrees from my phone?

If you’re about to:

• resolve conflicts
• rebase interactively
• do large refactors

Those are still best done at a keyboard.

What does “worktree is locked” mean?

Git lets you lock a worktree so it won’t be pruned/cleaned up automatically.

This is useful if the worktree lives on a disk or location that isn’t always mounted.

What does “prune” do, and when do I need it?

If a worktree folder is deleted incorrectly (not via git worktree remove), Git can end up with stale metadata.

git worktree prune cleans up those stale administrative files.

If you never delete worktree folders manually, you’ll rarely need this.

Can I use worktrees to keep long-running branches separate (not just hotfixes)?

Yes — that’s a great use.

Examples:

• keep main clean in the primary worktree
• keep release/<version> in a dedicated worktree
• keep a long-running refactor in its own worktree

It reduces context switching and makes it easier to do quick reviews.

Do worktrees share node_modules / build artifacts?

Not automatically.

Each worktree is a separate directory, so most tooling treats it as a separate project folder.

If you want shared caches, that’s usually handled by the language/tooling layer (pnpm store, Gradle cache, etc.), not Git.

Where should I put worktree folders?

I like putting them adjacent to the main repo folder, with clear names.

For example:

• repo/ (main worktree)
• repo--hotfix-123/
• repo--release-1.2/

The best naming scheme is the one that makes it obvious, from a phone screen, what you’re looking at.

Can I remove a worktree safely from my phone?

Yes, but follow one safety rule first:

• make sure it has no uncommitted changes
• and no unpushed commits you still care about

A quick “Changed files” review before removal is cheap insurance.

Is git worktree the same thing as git switch / git checkout?

No.

• switch/checkout changes what branch a single working directory points at.
• worktree add creates a second working directory so you don’t have to switch away.

Should I use worktrees instead of branches?

No — worktrees complement branches.

A good default is still:

• one branch per worktree

Can I use worktrees with submodules?

Yes, but be careful: each worktree has its own checkout state.

If submodules are part of your workflow, keep phone changes narrow and do the deeper “submodule surgery” at a keyboard.

Related guides

• Use your phone as a remote Git client
• Edit files on your computer from your phone