Repositories and worktrees

Put two sessions in the same folder and they will not fight loudly. They will fight quietly: one edits a file while the other is halfway through rewriting it, one stages the other's half-finished work, and the change you finally read is a mixture of two intentions that neither of them meant. Nothing in DevThrottle stops you doing this. A session's working folder is just a path, and two sessions may hold the same one.

The fix is not a rule about taking turns. It is giving each session a folder of its own - which git already knows how to do, and the Director already knows how to keep track of.

About ten minutes. You need one repository you can push from, and git on your machine - everything below is the Director driving git rather than replacing it.

1. Understand what a worktree actually is

   A worktree is a second working folder for a repository you already have, checked out on its own branch. It is not a second clone: there is one repository, one history, one set of remotes, and the new folder simply holds a different branch of it. Creating one costs a checkout, not a download.

   That is exactly the shape the problem wants. Two sessions, two folders, two branches, one repository - so they cannot touch each other's files, and their work still merges the ordinary way.

2. Make one, beside the repository

   From inside the repository

   git worktree add ../myapp-login -b login-form

   That creates the folder myapp-login next to your repository, on a new branch called login-form. Name both after the job rather than the session that will work there - the folder outlives it.

   Warning

   Put it beside the repository, not inside it. git will happily create a worktree in a subfolder, and it does not ignore it for you - so the repository around it starts reporting untracked content, which makes it look permanently dirty. A repository that always looks dirty is one whose change badge you stop believing.

3. Start a session in it

   Hit New Session in the toolbar and browse to the worktree folder - it is an ordinary folder, so it goes in the path box like any other. From that moment the session's world is that folder and that branch. The quiet fights from the top of this page are over: two sessions can no longer edit or stage over each other. What the worktrees still share is the repository itself - one history, one set of branches, one set of remotes and one configuration - so a session can still push, or move a branch the other cares about. Worktrees isolate the working files, not the repository. Everything else the dialog asks is covered by starting your first session - the only thing different today is the folder you point it at.

   Note

   Do not go looking for the worktree in the repository list - it is not there, and that is deliberate rather than a scan that missed it. Worktrees are shown under the repository they belong to, which is the next step.

4. See every worktree you have

   Two ways in, showing the same thing. From a session, open the Source Control tab and pick Worktrees in its left rail. Or open Repositories - pinned at the bottom of the main left rail - click the repository, and choose its Worktrees tab.

   Note

   One precondition: the Director only tracks repositories under a registered root folder. If the page answers "This folder is not under a registered root directory. Add its root under Repositories.", do exactly that - open Repositories, pick Root folders, hit + Add root folder, and point it at the folder that holds your repository. Then come back.

   Every worktree of that repository is listed, sorted into groups, and each row carries a one-line reason from the Director saying where it put that worktree. Read that line rather than the group heading above it: the line is the Director's own account of what it found in that particular folder.

   The worktree you just started a session in appears here like any other, with its branch and its own line. That is what this view is for - one place that answers "what have I got open, and where is it?"

   Once several sessions are running this way, the Cockpit's fleet map can answer a related question fleet-wide: pick By working tree in the pivot row and your running sessions are grouped by the name of the folder each one is working in, where grouping by repository would fold them back together. It is a picture of the sessions, not of the folders: a worktree nothing is running in does not appear there - this Worktrees page is where those live. Reading the map is its own tutorial.

Next

Which folders get scanned in the first place is on Repositories and GitHub. For reading what a session changed before you merge it, see Source control and history. And when one machine stops being enough - a separate problem with a separate answer - see Using more than one machine.