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.