Branches

A branch lets you, or an agent, try work without changing what everyone else sees. It covers everything a project holds at once: documents, app records, an app's own view and skill, and the code beside them. Merge it when it is right, or discard it and main is exactly as it was.

How it works

A branch is a set of copies. When a branch opens, it pins where every document on main stood. Anything on the branch reads main as it was at that moment until it writes. The first write to a document makes a copy that shares main's history, so merging it back is an ordinary merge. Nothing is copied until it is changed, so a branch that touches three documents costs three copies. A project with no code branches the same way.

Working on a branch. A session started on a branch reads and writes through it. Sessions work on main by default, so a person pairing with an agent sees its edits as they land. An agent about to change more than a handful of documents asks first whether to do it on a branch, so a large rewrite stays safe to throw away. You switch which branch your window shows from the project's row in the sidebar, and a pane open on a branch names it.

Code travels with it. When a session on a branch starts changing code, it opens a git branch of the same name in its own worktree, so the documents and the code for one piece of work stay together. See sources.

Compare before you merge. Comparing shows the branch's changes beside what changed on main since each copy was made: text, app records, new documents, and the code review beside them. Where the same paragraph or field changed on both sides, it is flagged, and Merge waits until someone picks: keep the branch's, keep main's, or edit. The pick is written as a change on the branch, so history shows who resolved what. Comparing writes nothing to main.

Merge or discard. Merging saves a version of main first, merges each copy into main with its authors kept, and merges the code branch's pull request if there is one. A merge that is interrupted, say by a machine moving, resumes from where it stopped and says how far it got. Discarding marks the branch discarded and nothing else: main never read a copy, so there is nothing to put back. That is the undo you want after a pile of changes, rather than thirty separate undos.

Keeping up with main. Update from main brings main's newer work into an open branch, and shows overlaps the same way a merge does. A branch can also open from a saved version, to pick up where the project stood last week; merging it back is how the past comes back.

A branch is one level deep: it opens from main or from a version, never from another branch. Main never reads a branch's copies.

Using it as you build

Start a session on a branch to keep its work apart. Its selection is recorded on the session's own log, so a session whose VM moves or restarts comes back on the same branch, never silently on main.

On a branch, change a document's content and its title or folder in two separate writes: content lands in the copy, while title and place belong to main's catalogue until the merge. Documents created or deleted on a branch reach main only when it merges.

An app's users run its installed version, not whatever its view holds right now, so editing an app on a branch, or on main, changes nothing anyone runs until someone installs it (history).

Limits

• A merge spans several documents and maybe a pull request, so it is not atomic. It reports any partial completion and resumes forward, rather than claiming the whole branch has landed.