# Worktrees

A worktree lets a session work on its own branch, in a folder of its own, so several agents can work
in one repository at once without touching each other's files or yours.

## Running a session in a worktree

When the folder you pick in Create session is in a git repository, **Run in a new worktree** is
offered, off by default. With it on, Moontors:

- makes a new branch from your checkout's current commit (below);
- puts the worktree under `~/.moontors/worktrees/`, in a folder for the repository and, inside it,
  one named for the branch, so your own folders and `.gitignore` stay as they are;
- copies in the files your project lists (below);
- starts the session there, in the same place inside the repository as the folder you picked.

The branch is named by a prefix and the title you give in Create session: the title in lowercase
letters, digits and dashes, cut to 40 characters. With the default prefix, `Fix the login` gives
`moontors/fix-the-login`. Without a title, or with one that has no Latin letters or digits, a short
id stands in. Create session shows the name under **Branch**. If that branch or its folder is
already taken, the session gets `-2`, `-3` and so on at the end.

The prefix is `moontors/` until you change it with **Change prefix**, which applies to every new
worktree. It can be up to 40 characters, and must be one git accepts at the start of a branch name.

The card shows the repository and the branch. A worktree session stays in its worktree: `/cd`
can't move it.

Your checkout's uncommitted changes stay where they are: the worktree starts from the last commit,
and the session says so.

If the switch can't be turned on, it says why: git isn't installed, git is older than 2.23, git
didn't answer in time, or the repository has no commits yet.

If your repository has a post-checkout hook that fails or takes too long, the session still starts,
with a note.

## Copying files into a worktree

Files that git doesn't track, such as `.env`, aren't in a new worktree. List them on the project,
one pattern per line, relative to the project folder: `.env`, `.env.local`,
`config/*.local.json`.

- Edit them in Create session once **Run in a new worktree** is on, where the list is saved to the
  project when you create the session. Or edit them with **Edit project**, the pencil beside the
  Project menu once you've picked a project there.
- A project holds up to 50 patterns, of up to 200 characters each. A pattern must stay inside the
  project folder, so an absolute path or `..` is refused.
- `**` doesn't reach names that start with a dot, so name those. Nothing inside a `.git` or
  `node_modules` folder is copied.
- Files are copied, never linked, and never replace a file that's already there.
- A pattern that matches nothing, or more than 200 files or 64 MiB, is skipped with a note and
  copies nothing. The session still starts.

## Archiving

Archiving a session stops its agent and removes it from the board, once you confirm. For a worktree
session it also cleans up the worktree:

- If the worktree has uncommitted changes, or commits that aren't pushed, a second confirmation
  says how many, and whether the branch stays. Uncommitted changes don't come back if you reopen
  the session: only what's committed on the branch does.
- The worktree folder is removed.
- The branch is deleted only when it holds nothing beyond the commit it started from. Otherwise it
  stays.
- A worktree that another session still uses, such as a fork's, is left as it is.
- If the repository itself is gone, the worktree folder is left where it is, with a note naming it,
  for you to delete.

An archived session comes back with **Reopen**, from the Archived view. Its worktree is made again
from its branch, and the project's files are copied in again: see
[Sessions and the board](/docs/sessions-and-board/).