# vcs spec (draft 2, October 28, 2026)

`vcs` is a placeholder name. The real name comes before the public preview.

vcs is open-source version control where nobody waits and nothing gets lost. It has its own model and its own CLI. Git is a bridge in and out, not the foundation. It runs on its own for one person offline, and it gets a server (Upstream, or one you host) when work is shared.

Three promises:
- **Nobody waits.** Landing is the server's job, so nobody's work is refused because someone else landed first. Making a workspace takes seconds, not a clone and a reinstall.
- **Nothing is lost.** Your work saves itself, and `vcs undo` takes back what you did, including a land. A change follows you to another machine, and deleting a workspace folder loses nothing.
- **Private where you need it.** A folder can be visible to only some people. Your `.env` files are yours alone, and secrets are checked before anything lands.

The plan behind this spec, with the research and the order of work, is `reports/Upstream version control plan Oct 2026.md`.

## 1. The words

| Word | Meaning |
|---|---|
| **change** | One piece of work. It has an ID made of letters (`rtnbkcvx`; the first 4 or more letters are enough) and keeps that ID from start to finish. It holds every save. It replaces git's commit, branch, stash and reflog. |
| **main** | The shared line of a project. It only moves when a change lands, and each landing makes a new numbered **version**: main 1, 2, 3 and so on. Numbers are always versions and letters are always changes. |
| **land** | Putting a change on main. The server merges it with whatever landed since the change started, runs the project's checks on the exact result, and adds it as the next version. If something conflicts, main doesn't move and you're told exactly where. |
| **workspace** | A folder working on one change. You can have as many as you like, and each holds one change at a time. Your work lives in the change, not the folder. |
| **save** | A snapshot of a change. Saves happen by themselves, and every save is kept. |

There's no staging, no commit command, no branch names and no pull or rebase before landing.

## 2. A day with vcs

```
$ vcs get upstream.codes/acme/shop
workspace  ~/shop  (upstream.codes/acme/shop)
change     rtnbkcvx  new, empty, on main 48190
next: edit files, then vcs land -m "what you did"

$ # ...edit src/auth/login.ts...

$ vcs land -m "Fix login redirect loop" -m "Why: users with expired sessions bounced between /login and /home. Checked: auth tests pass."
landed     rtnbkcvx as main 48214  "Fix login redirect loop"
merged     with 23 versions that landed since main 48190
change     qwhmdzst  new, empty, on top of what you just landed
next: keep working, or vcs sync to bring in others' work
```

Two agents work in parallel by each getting their own workspace:

```
$ vcs get upstream.codes/acme/shop ~/shop-billing
$ vcs get upstream.codes/acme/shop ~/shop-search
```

Both land whenever they're ready, in any order. Neither waits for the other or pulls first.

## 3. Commands

Four commands cover nearly all work: **get**, **status**, **land** and **sync**. **undo** covers mistakes.

| Group | Command | What it does |
|---|---|---|
| Start | `vcs get <project> [folder]` | Make a workspace for a project (`--lazy`: each file comes when it's first opened). |
| | `vcs mount [folder] [--stop]` | Start a lazy workspace's mount again, or stop it. |
| | `vcs workspaces [add <folder> [--on <change>] \| clean]` | This project's workspaces on this machine (one per agent): list them, add one next to this one (on main, or on a change that hasn't landed), or remove the ones whose work is done. |
| | `vcs init [folder]` | Start a new project that lives only on this machine. |
| | `vcs import <git-repo> [folder]` | Make a project from a git repository, with its history. |
| | `vcs publish <project>` | Put a local project on a host. |
| | `vcs git [resume]` | Where git clones the project, and whether that git view is current. |
| | `vcs login [host]` | Sign in (default host: upstream.codes). |
| See | `vcs status [change]` | Where you are and what to do next. |
| | `vcs diff [path...]` | What a change changes. |
| | `vcs log [version\|change\|path]` | History of main, open changes, saves or operations, or the versions that changed a path. |
| | `vcs blame <file>` | The version that last changed each line. |
| | `vcs show <file> [--from <version\|change>]` | Print a file as it is in main, or in a version, change or save. |
| | `vcs tag [name] [version]` | Name a version of main (`v1.0`); a name works wherever a version number does. `--remove` takes it off. |
| | `vcs bisect <good> <bad> --run "<command>"` | Find the first version of main where a command fails. |
| | `vcs verify [version]` | Who signed the land that made a version, checked here. |
| Work | `vcs new ["title"]` | Start another change. The current one is kept. |
| | `vcs line [name] [--from <version>]` | The project's release lines, or a new one (`1.x`) from a version of main. |
| | `vcs describe "text"` | Set the current change's description. |
| | `vcs switch <change>` | Put this workspace on another change. |
| | `vcs drop [change]` | Abandon a change. |
| Finish | `vcs sync` | Bring the change up to date with main. |
| | `vcs land [change]` | Put a change on main (or on its release line; `--to <line>` brings a change over to one). |
| Fix | `vcs undo [version]` | Undo the last vcs command in this workspace, or take a landed version back out. |
| | `vcs restore <path...>` | Bring files back from an earlier point. |
| | `vcs purge <path>... [--yes]` | Take files out of the project's whole history and delete their content (owners on a host). |
| | `vcs gc [--older 30d] [--dry-run]` | Clean up what this machine keeps: old saves, and objects nothing needs. |
| Share | `vcs access <change\|path> [who...]` | See or set who can see a change or a folder. |
| | `vcs group <name> [@person...]` | See or set one of the project's groups. |
| | `vcs approve <change>` | Approve someone else's change; the last approval a project needs lands it. |
| | `vcs key` | Make this machine's signing key and add it to your account; your lands are signed from then on. |
| | `vcs settings [approvals=N] [git=on\|off] [signed=required\|optional]` | See or set the project's host settings: approvals needed to land, whether main is copied to git, and whether lands must be signed. |
| | `vcs check` | Check this machine's objects and the host's copy of the project for damage. |
| | `vcs rollback --to <time>` / `--undo <bookmark>` | Put a hosted project back as it was (owners, the last 30 days), or reverse that. |
| Help | `vcs guide` | Print the guide for coding agents ([GUIDE.md](GUIDE.md)). |
| | `vcs help [command]` | Help for a command. |

Every command saves the workspace before it does anything else. Every command takes `--json`. Every command that leaves something to do ends with a `next:` line.

### References

- `48213` is version 48213 of main, and `main` is the latest version.
- `rtnbkcvx` (or a unique prefix of 4 or more letters, like `rtnb`) is a change at its latest save.
- `rtnb:14` is save 14 of change `rtnb`.
- `1.x` is release line 1.x at its latest version, `1.x/3` its version 3, and `1.x/0` the version of main it started from.
- `--at "10 min ago"`, `--at 15:30` or `--at 2026-10-27T15:30` is a point in time in this workspace's saves.

### vcs get

```
vcs get <project> [folder] [--change <id>] [--only <path>...] [--line <line>] [--lazy]
```

Makes a workspace. `<project>` is `host/owner/name` (`upstream.codes/acme/shop`) or the path of a local project. The folder defaults to the project's name.
- The workspace starts on a new, empty change on the latest main.
- `--change <id>` starts on an existing change instead. If another workspace holds that change, this one takes it over (see section 7).
- `--only src/web docs` gets just those folders, for big projects.
- `--line 1.x` starts on a new change on that release line; `vcs land` lands there.
- `--lazy` (Linux) makes the workspace a mount that shows every file at once and fetches each one from the host the first time it's opened. Only the folders and the files' sizes come first. What you write goes to a real folder of the workspace's (in vcs's own folder), so saves, lands and syncs work as in any workspace. After a restart, `vcs mount` (or any vcs command in the folder) starts the mount again. macOS needs FSKit and comes later.
- History is fetched when `log`, `diff` or `restore` need it.
- Files come from a cache shared by all your workspaces. Folders listed under `copy` in `vcs.toml` (like `node_modules`) are copied from your most recent workspace of the same project, copy-on-write where the disk supports it.
- Your private files (section 6) come along.

### vcs init, import, publish, login

- `vcs init [folder]` makes a local project with no server. Landing works locally, and main is numbered locally.
- `vcs import <git-repo> [folder] [--to <project>]` reads a git repository (a folder, a URL, or `upstream.codes/owner/name`) with the git on your machine. Each commit on the default branch's first-parent line becomes a version, in order, in a local project in a folder named after the repository. `--to upstream.codes/acme/shop` then publishes it. `vcs import <git-repo> --change <branch>`, run in a workspace, brings one git branch in as a change instead. Section 9 covers the rest.
- `vcs publish <project>` puts a local project on a host. History and version numbers are kept, and from then on the host orders main.
- `vcs login [host]` opens the host's sign-in page in the browser and waits while you approve it (upstream.codes uses Upstream's sign-in). Hosts without one take a token: `vcs login <host> --token <token>`. Agents and CI set `VCS_TOKEN` instead.

### vcs status

```
$ vcs status
project    upstream.codes/acme/shop
workspace  ~/shop
change     rtnbkcvx  "Fix login redirect loop"  open, yours
based on   main 48190  (main is at 48213; land merges the difference)
saved      3s ago  (save 14)
files      M src/auth/login.ts
           A src/auth/redirect.test.ts
next: vcs land
```

`vcs status <change>` shows any change you can see, including its landing state.

### vcs diff

```
vcs diff [path...] [--change <id>] [--from <ref>] [--to <ref>] [--stat]
```

By default, it shows what the current change changes compared with its base. `--from`/`--to` compare any two references (`vcs diff --from 48100 --to main`). The output is unified diff, like git's.

### vcs log

```
vcs log [-n 20]              recent versions of main
vcs log 48213                one version: description, author, files
vcs log rtnb                 one change: state, saves, description
vcs log --changes            open changes you can see: who, state, which workspace
vcs log --saves              saves of the current change
vcs log --ops                operations in this workspace (what undo walks back through)
vcs log src/auth             the versions that changed a file or folder (added, modified, removed)
vcs log --line 1.x           a release line's versions
vcs blame src/auth/login.ts  each line with the version that last changed it
```

History follows files that moved: `vcs log` shows "(from old/path)" at the version that moved one, and goes on back through its old name; `vcs blame` does the same. A move is a file that went from one path to another whole or with at least half its lines kept (`vcs status` shows it as `R old -> new`).

`vcs bisect <good> <bad> --run "<command>"` finds the first version of main where the command fails, by binary search over the numbered versions. Each version it tries is written to a folder of its own (the workspace's files don't change; `--in <folder>` keeps it), and the command runs there: exit 0 means good, 125 means it can't tell (that version is skipped), anything else means bad.

A path is told apart from a change by having a `/` or `.`, by not looking like a change ID, or by being a file or folder in the workspace. Hosts work out a path's history where the versions are, so a machine with only recent history still sees all of it. Each version keeps the paths it changed, so a path's history reads only the versions that touched it: on 20,000 versions, `vcs log <file>` takes about 10 ms and `vcs blame` 40 ms (git: 20–90 ms and 210 ms). Private paths have no history or blame for people who can't see them.

### vcs new, describe, switch, drop

- `vcs new ["title"]` saves and keeps the current change, then starts a new change on the latest main. The workspace's files become latest main.
- `vcs new ["title"] --on <change>` starts the new change on top of another change that hasn't landed yet (stacking). Landing the top change lands the whole stack (section 4).
- `vcs describe "Title" ["Body"...]` sets the current change's description. The first line is the title.
- `vcs switch <change>` saves and keeps the current change, then puts the workspace's files on another change. If another workspace holds that change, this one takes it over.
- `vcs drop [change]` abandons a change (the current one by default). A dropped current change is replaced by a new empty change on the latest main. `vcs undo` brings it back.
- `vcs new ["title"] --line 1.x` starts the new change on release line 1.x's latest version instead of main.

### Release lines

A release line is a named line of versions next to main, for a maintained `1.x` while main goes on. `vcs line 1.x --from v1.0` starts one from a version of main (or a tag; main's latest by default), and `vcs line` lists them.
- A change started on a line (`vcs get --line 1.x`, `vcs new --line 1.x`) lands there as the line's next version (`1.x/1`, `1.x/2`...); the workspace stays on the line, and `vcs sync` brings in the line's newest version.
- `vcs land <change> --to 1.x` brings a change over: for one that landed on main, what it did there (its version against the one before); for an open one, its own edits. The change itself stays as it was. If the edits conflict with the line, the workspace goes on a new change on the line with the conflicts marked, to fix and land.
- People who can land put versions on a line; main's review rules and approvals are for main.
- The git view has each line as a branch of its name, each version a commit on it (with a `Vcs-Line: 1.x/3` trailer).

### vcs sync

Brings the current change up to date with the latest main, along with any unlanded changes under it. The change's base becomes the latest main. Conflicts are written into the files with git-style markers, and you can keep working while they're there.

```
$ vcs sync
synced     rtnbkcvx onto main 48213  (was main 48190)
conflict   src/auth/login.ts  lines 40-58
next: fix the marked lines in src/auth/login.ts, then vcs land
```

Markers look like this:

```
<<<<<<< main 48213
  return redirect(session.next ?? "/home")
=======
  return redirect(safeNext(session.next))
>>>>>>> your change rtnbkcvx
```

A conflict counts as fixed once the markers are gone from that spot. For binary files, your version stays in place, and `vcs restore <file> --from main` takes main's instead. Sync exits with 3 when it leaves conflicts, and `vcs land` refuses (exit 3) while any are left.

You never need to sync before landing. Sync when you want others' work in your files, or after a land reports a conflict.

### vcs land

```
vcs land [change] [-m "Title"] [-m "Body"]... [--allow-secrets]
```

Saves, then asks the server to land the change (the current one by default) and waits for the result. It needs a description, from `-m`, `vcs describe`, or a title given to `vcs new`. `-m` sets the change's description, so after a failed land a plain `vcs land` reuses it. Section 4 has the details. Outcomes:

| Outcome | Exit | What happened | Next |
|---|---|---|---|
| landed | 0 | The change is main N. The workspace moves to a new, empty change on top of it, and your files don't change. | Keep working. |
| conflict | 3 | Main didn't move, and your change is unchanged and saved. The conflicting files are listed. | `vcs sync`, fix, `vcs land` |
| checks failed | 4 | Main didn't move. A `[land] run` command failed (its output is printed). Required checks on Upstream run on the change request instead (section 4). | Fix, then `vcs land` |
| waiting | 5 | You can't land this on your own: your token can't land, or you're a reader or an outside contributor. The people who can land it are asked. The workspace moves to a new change on top of it, so later edits don't change what's waiting. Or the repository's rules send it through review: the output has its change request's link, the workspace stays on the change, and it lands when the change request's approvals and checks pass. | `vcs status <change>` later |
| secret | 8 | Something in the change looks like a secret. The file and line are printed. | Remove it, or move it to a private file |
| offline | 6 | The host can't be reached. The change is saved. | `vcs land` again later |

Landing someone else's change (`vcs land rtnb`) is how a person with landing rights accepts an agent's change, a teammate's change or an outside contributor's change.

### vcs undo

Undoes the last vcs command in this workspace. Run it again to go further back, and `vcs log --ops` lists what it will walk through.

| Undoing | Does |
|---|---|
| land | Adds a new version to main that takes the landed change back out, then reopens the change in this workspace. Edits made since the land stay in the files and become part of the reopened change. If later versions changed the same lines, undo stops and says so. |
| sync | Puts the change and the files back as they were before the sync. |
| new, switch | Goes back to the previous change and its files. |
| drop | Brings the change back. |
| describe, access | Puts the old description or rule back. |
| restore | Puts the files back as they were before the restore. |

`get`, `init`, `import`, `publish` and `login` aren't undone. Delete the folder, or use the host.

`vcs undo <version>` takes an earlier landed version back out without undoing anything else. It adds a new version to main that reverses it, and the change it came from becomes open again (`vcs switch <change>` to work on it). It stops and says so if later versions changed the same lines.

### vcs restore

```
vcs restore <path>...                       back to how it is in the change's base
vcs restore <path>... --at "10 min ago"     from your own earlier save
vcs restore <path>... --from <ref>          from a version, a change or a save
```

`vcs restore .` restores everything. Restoring is itself saved, so it can be undone.

### vcs access

```
vcs access <change|path>                    show who can see it
vcs access <change|path> <who>...           set who can see it
vcs access <change> <who>... --edit         also let them take the change over and work on it
```

`<who>` is `me`, `@person`, `@group` (one of the project's groups, set with `vcs group`), `team` (everyone with access to the project) or `everyone` (public projects only). Section 6 has the rules.

## 4. Landing

1. **Saved first.** `vcs land` saves, then sends the change's final save. Edits made after that point go into the next change.
2. **Ordered by the server.** Each project's main has one queue, and landings are decided one at a time in the order they arrive. A land is never refused because someone else landed first.
3. **Merged on the server.** The server does a 3-way merge of each file: the change's base, the latest main and the change.
   - Text files merge line by line, as in git.
   - Code merges where git stops: two changes that each add something at the same spot (two new functions, two new tests) both go in, one after the other; and a block of imports takes both sides' new imports, in order (JavaScript and TypeScript, Python, Rust, Go, Java and Kotlin, C# and Swift).
   - JSON files merge by key, and so do TOML files (`Cargo.toml`, `pyproject.toml`), so two changes that each add keys to the same file both land.
   - A file moved on one side and edited on the other lands as one file at its new path, edited.
   - Anything that can't be merged is a conflict (two new files at the same path are one too), and the land stops with the list of files and lines.
4. **It lands at once,** unless the repository's rules say otherwise. On Upstream, the repository's Rules page (required checks, approvals, "changes only through review") applies to vcs as it does to git:
   - **No rules:** the land goes on main at once.
   - **Rules:** `vcs land` turns the change into a change request, merged onto main: branch `vcs/<change>`, a change request with auto-merge on, and its link (exit 5). CI runs as for any change request, and Upstream merges it once its approvals and checks pass; the merge comes into vcs main as that change. Running `vcs land` again after more edits updates the same change request, and `vcs status` shows where it stands. The change request page is the review screen: diff, comments, approvals, checks.
   - **A change into a private folder** can't be shown in git, so it can't be a change request: someone else who can see the folder approves it with `vcs approve`. Where checks are required, it can't also touch other files (CI can't see private folders): land the private part as a change of its own.
5. **One change, one version.** The version's description is the change's description, and its author is the change's author (a person, or an agent acting for one).
6. **Stacks land in order.** Landing a change that sits on unlanded changes lands all of them, bottom first, as consecutive versions. If one conflicts, the ones below it stay landed, and it and the ones above it don't. The error says which.
7. **After landing,** the workspace continues on a new, empty change on top of what landed. Your files don't change. vcs never changes files in a workspace unless you run a command that says it does: sync, new, switch, restore or undo.
8. **Who can land comes from the host.** On Upstream, a repository's admins and writers land; anyone else's land waits, and the people who can land are asked. A token only does what its scopes allow, so a read-only token's land waits too.
   - **Approvals:** with `vcs settings approvals=1` (or more), a land waits until that many people other than the change's owner run `vcs approve <change>`. An approval counts for exactly what was approved, so editing the change needs a new one. The last approval lands the change.
9. **Outside contributors** don't need a fork. They get the project, make a change, and `vcs land` asks the maintainers, who land it or don't.
10. **At a set time:** `vcs land --at "fri 9:00"` (or `"in 2h"`, `"tomorrow 9:00"`, `"2026-11-02 09:00"`). The host keeps the change as it is now and lands it then; the workspace goes on with a new change on top. Under rules, its change request opens now, so it can be reviewed, and merges from that time once it's ready. The host keeps the lander's token (sealed) only until then. `vcs land <change>` lands a kept one now; `vcs drop <change>` cancels it.
11. **Together:** `vcs land --with ../api [--with ../web]` lands this workspace's change and each other workspace's change (one per project, on the same host) together: all of them, or none. Each project's main is held at its landing's last step until every part is ready. Under rules in any of them, or with `--at`, each part waits (in review, or held as it is), and the host lands them all once every change request can merge and the time has come.
12. **Signed:** after `vcs key`, every land from this machine is signed with its Ed25519 key, over the change, its base and content, and its description and author. The host checks the key is on the lander's account and the signature matches, keeps it with the version, and adds `Vcs-Signed-By: @handle ed25519:<key>` to its git commit. `vcs verify [version]` checks it again here. With `vcs settings signed=required`, unsigned lands are refused.

## 5. Saving, undo and restore

- **Every vcs command saves first.** Between commands, a background **saver** saves any workspace within a few seconds of a file changing.
  - The saver is one process per machine. It starts with the first vcs command and stops after 30 minutes with no activity.
  - `VCS_SAVER=0` turns it off.
- **Saves stay local first,** then upload to the host in the background. On the host they're visible only to you and your agents, unless you share the change.
- **Saves include every file that isn't ignored.** Ignored files (from `.gitignore`, same syntax) are never saved and never land.
- **Kept:** every landed version, and every save of a change that's still open. Saves of a change that landed or was dropped go after 30 days, on hosts and (with `vcs gc`, which the saver runs once a day) on each machine, along with the objects nothing kept needs.
- **`vcs purge <path>... --yes`** takes files or folders out of the project's whole history, for a secret or a big file that should never have landed: every version of main and of each release line, every change and save, loses them, and their content is deleted (on a host, once nothing else there has the same bytes). Versions keep their numbers; their IDs change. Without `--yes` it only says what it would do. On a host it's for owners: the git view's main is written again from the first version that had them (a force push), other machines take them out when they next sync, and the project can't be rolled back to before the purge. The files go from this machine's workspaces too, so copy anything you still need first. A secret that leaked should still be changed.
- **`vcs undo`** walks back through operations. **`vcs restore`** walks back through file contents. Between them, the only way to lose work is to delete a folder before its last edits were saved, which takes under a few seconds with the saver running. Running any vcs command (`vcs status`) before deleting a folder makes sure.
- **`vcs check`** reads every object this machine keeps and checks it against its ID, and asks the host to check its copy: every version's ID against its contents and the version before it, and that everything main needs is stored. It exits 1 if anything is damaged. (21,178 versions and main's files: 0.6 s on Upstream's host.)
- **`vcs rollback --to <time>`** (owners) puts the whole hosted project back as it was at a time in the last 30 days: versions, changes, saves and settings. It prints a bookmark, and `vcs rollback --undo <bookmark>` puts it back as it was before. Workspaces follow on their next `vcs sync`, keeping their own unlanded edits. A project with a git view pauses it, since git main still has what came after; `vcs git resume` keeps those commits in git's history (as a second parent) while main's files are the rolled-back ones.
- **Nothing can write into `.git` or `.vcs`.** A path part can't be either in any spelling a disk treats as the same (`.GIT`, `.git.`, `git~1`), nor hold a backslash: hosts refuse to land one, imports leave them out, and vcs never writes one into a folder or picks up a nested `.git` or `.vcs` folder. On Windows, vcs refuses to write names Windows can't hold (`aux.c`, `a:b`) rather than write somewhere else.

## 6. Access

Who can see what:

| Thing | Default | Changed with |
|---|---|---|
| An open change | You, and agents acting for you. The maintainers too, once `land` has asked them. | `vcs access <change> <who>` |
| A path in the project | Everyone with access to the project | `vcs access <path> <who>` (project owners only) |
| `.env` and `.env.*`, except `.env.example`, `.env.sample` and `.env.template` | **Mine**: only you | `vcs.toml` `[mine]` or `vcs access <path> me` |

- **A private path** (for example `vcs access billing/ @sam`) is left out of the workspaces, diffs, logs and API answers of anyone it isn't shared with, and out of the git view for everyone (section 9). Project owners see every path.
  - It lands normally, and main's version numbers are the same for everyone.
  - A version that changed only paths you can't see shows as "a private change", without its description.
  - Writing into a path you can't see is refused when you land.
  - Agents see what the person they act for sees.
- **Mine files** are saved and follow you to every workspace of the project you make, so a new workspace has your `.env` already. They never land, never show to anyone else and never appear in git views. On a host, only you can read them.
- **Secret check:** before landing, added lines are checked for things that look like real keys and tokens. A match stops the land (exit 8) with the file and line. `--allow-secrets` overrides it, and the override is recorded. Saves are private to you, but once you remove a flagged secret, it's also scrubbed from that change's earlier saves. This is the one case where saves are rewritten.
- **Path rules** are project settings, not files in the project, so a private folder's name isn't exposed to people who can't see it.

## 7. Workspaces

- A workspace is a normal folder with a small `.vcs/` folder inside. There is no `.git`. Git commands don't work in a workspace; section 9 covers git.
- Making a second workspace of a project takes seconds. Files come from a shared cache, copy-on-write where the disk supports it (APFS clones on macOS, reflinks on Btrfs and XFS).
- `vcs.toml` can list build folders to copy from your most recent workspace of the same project:

  ```toml
  [workspace]
  copy = ["node_modules", "target"]
  ```

- **One change per workspace, one workspace per change.** If another workspace (on this machine or another) holds a change and you `switch` to it or `get --change` it, you take it over. The other workspace finds out on its next command. If it had edits that weren't saved yet, they're saved into a new change labelled "rescued from rtnbkcvx", so nothing is lost.
- **Deleting a workspace** is just deleting the folder. Its change stays, and `vcs log --changes` lists it, ready for `vcs get --change`.
- **One workspace per agent.** Two processes editing one folder at once are the classic way to lose work silently. vcs keeps every save, but it can't tell two writers apart.

## 8. Offline and local projects

- **Offline,** everything works except land, get, access and the parts of log and status that need the host's latest main. Sync uses the last main this machine saw. Saves queue and upload once you're back online.
- **A local project** (`vcs init`) has no host at all, and landing is local. `vcs publish` moves it to a host whenever you want, with history and version numbers kept.
- **Full copies:** anyone who can read a project can read every version of it, through vcs or its git view, so a public project can always be copied or mirrored.

## 9. Git and GitHub

vcs is native, but git still works around it, so nobody has to switch at once.

- **Import:** `vcs import <git-repo>` reads a repository with the git on your machine.
  - Each commit on the default branch's first-parent line becomes a version, in order, with its message, author and time.
  - Each git file and folder is read once, however many commits share it.
  - Submodules come along as pointers to their commits: a workspace shows each as an empty folder (as git does before `git submodule update`), and the git view keeps them. Paths whose names aren't UTF-8 are left out (the import says how many).
- **"Use vcs" on Upstream:** a repository's admins turn vcs on or off in its settings (or when they create it). On links a project to the repository; when it has git history, the first `vcs get` brings main's history in (on that machine, as `vcs import --to` does). Off, vcs takes no more lands and the repository is git only, with everything kept for turning it on again.
- **Publishing an import** (`vcs import <repo> --to <project>`, or a later `vcs publish`) also copies the original git history, every branch and tag byte for byte, to the project's git view, and main there is the last imported commit. A repository that already has that history (importing a project from its own Upstream repository) is left as it is.
- **The git view:** every hosted project on Upstream is also its Upstream repository, so git clones it as usual (`git clone https://git.coline.app/acme/shop.git`), and Upstream's GitHub mirror keeps a GitHub copy current.
  - Main is a git branch, and each version lands there as a commit within seconds. Its message ends with `Vcs-Change: rtnbkcvx` and `Vcs-Version: 48214` (and `Vcs-Signed-By` for a signed land). A busy project's versions go in at most one push a second, many versions to a push.
  - Each release line is a git branch of its name, from its version of main's commit.
  - After `vcs purge`, main (and each line) is written again from the first version that had the purged paths, with a force push; commits before it keep their IDs. A repository that refuses force pushes to main pauses the git view and says so.
  - The git view is one view for everyone who can read the repository, so it leaves out every private path.
  - **Your own git URL:** someone who can see private folders the git view leaves out gets `https://vcs.coline.dev/<owner>/<name>.git` (`vcs git` shows it; their token is the password). It's main as they see it. Everyone with the same view shares one chain of commits, which starts at the version that was main when that view was first used. Main is its only branch, and a push to it (on top of its latest commit) lands like `vcs land`.
  - `vcs git` shows where it clones from and which commit is the latest version. `vcs settings git=off` stops copying main to git (for a team that's left git behind); `git=on` catches it up.
- **Git branches come in as changes:** `vcs import <git-repo> --change <branch>`, run in a workspace, makes the branch a change on top of the version it started from, ready for `vcs land`. It works on any branch of the git view, and on git commits pushed to main.
- **Pushing to git main works too.** On Upstream, commits pushed to git main come into vcs within seconds of the next request (Upstream says when a repository gets a push): each commit on git main's first-parent line becomes a version with its message and author, already in git. If vcs landed meanwhile, git main's commits merge into one version and the git view's next push makes it a merge commit of both lines, so neither side loses anything. Private paths aren't in git, so they stay as they were.
- **When they can't come in by themselves** (git and vcs changed the same lines, a commit touches a private path, a force push, or over 32 MB at once), the git view pauses instead of overwriting anything, and `vcs git` says why. Bring those commits in with `vcs import <repo> --change main` and land them, then `vcs git resume`: the next version's commit keeps the outside commits as a second parent, so git history loses nothing.

| git | vcs |
|---|---|
| `git clone` | `vcs get` |
| `git status` | `vcs status` |
| `git add` + `git commit` | nothing; it saves itself |
| `git commit -m` + `git push` | `vcs land -m` |
| `git pull`, `git rebase main` | `vcs sync` |
| `git checkout -b`, `git switch -c` | `vcs new` |
| `git switch <branch>` | `vcs switch <change>` |
| `git stash` | `vcs new` (the current change stays saved) |
| `git checkout -- <file>`, `git restore <file>` | `vcs restore <file>` |
| `git reflog`, `git reset --hard HEAD@{1}` | `vcs undo` |
| `git log` | `vcs log` |
| `git log -- <file>`, `git blame <file>` | `vcs log <file>`, `vcs blame <file>` |
| `git show <rev>:<file>` | `vcs show <file> --from <version>` |
| pre-commit and pre-push hooks | `[land] run` in `vcs.toml` |
| `git tag v1.0`, `git push --tags` | `vcs tag v1.0` (the git view gets it as a git tag) |
| `git worktree add` | `vcs get <project> <folder>` |
| `git revert <commit>` | `vcs undo <version>` (or plain `vcs undo` right after the land) |
| `git bisect` | `vcs bisect <good> <bad> --run "<command>"` |
| a `release/1.x` branch, `git cherry-pick` onto it | `vcs line 1.x`, `vcs land <change> --to 1.x` |
| `git filter-repo --path <file> --invert-paths` | `vcs purge <file> --yes` |
| `git commit -S`, `git verify-commit` | `vcs key` (then every land is signed), `vcs verify` |
| partial clone, VFS for Git | `vcs get --lazy` |
| a pull request | `vcs land` without landing rights, or `vcs access <change> team` |
| a branch someone pushed with git | `vcs import <repo> --change <branch>` |

## 10. Agents

- `vcs guide` prints [GUIDE.md](GUIDE.md), a short instruction file. Agent harnesses can load it as a skill or paste it into `AGENTS.md`.
- **Tokens:** agents use a token in `VCS_TOKEN`, made by a person on the host. The token acts for that person and can be limited further, to some projects and to reading or writing. The host enforces the limits, so instructions don't have to.
- **Parallel agents** each get their own workspace with `vcs get`. Second and later workspaces take seconds, and a project's `copy` folders come along.
- **Output:** short text with a `next:` line, or `--json` with the same fields plus `next`. Exit codes are stable (section 11).
- **Without a checkout:** `POST /projects/{owner}/{name}/edits` lands file edits in one call: contents (text, or base64 for binary files), deletions, which files are executable, a title and the version they were made on. It becomes a change of the caller's and lands like any other: merged, waiting for approvals or landing rights, refused for secrets unless asked. Upstream's host also speaks MCP at `https://vcs.coline.dev/mcp` (the same tokens), with tools to read a file, list a folder, see recent versions and land edits, for agents that have no shell or disk. Upstream's own API and MCP server read files, search and diff the git view.

## 11. Output and exit codes

Text output is short and stable: one fact per line, a label in the first column, and `next:` last. Errors start with `error:` and always say whether anything changed.

```
error: can't land rtnb: 2 files conflict with main 48213
  src/auth/login.ts
  assets/logo.png  (binary)
main didn't change; your change is saved
next: vcs sync, fix the conflicts in those files, then vcs land
```

`--json` prints one JSON object:

```json
{
  "ok": false,
  "error": { "code": "conflict", "message": "can't land rtnb: 2 files conflict with main 48213" },
  "main": 48213,
  "conflicts": [
    { "path": "src/auth/login.ts", "kind": "text" },
    { "path": "assets/logo.png", "kind": "binary" }
  ],
  "next": ["vcs sync, fix the conflicts in those files, then vcs land"]
}
```

| Exit | `error.code` | Meaning |
|---|---|---|
| 0 | | OK |
| 1 | `failed`, `not_found`, `empty_change`, `nothing_to_undo` | Didn't work. The message says why. |
| 2 | `bad_usage`, `no_description` | The command was wrong. `next` shows the right form. |
| 3 | `conflict` | Conflicts. Sync and fix. |
| 4 | `checks_failed` | A `[land] run` command in `vcs.toml` failed, or a required check failed on the merged result. |
| 5 | `waiting` | Someone else has to act (land or approve). Don't retry in a loop. |
| 6 | `offline` | The host can't be reached. The work is saved. |
| 7 | `not_allowed`, `not_logged_in` | Permissions. |
| 8 | `secret` | Possible secret in the change. |

## 12. vcs.toml

Optional, at the project's root, and it lands like any file.

```toml
[workspace]
copy = ["node_modules", "target"]    # build folders new workspaces copy from your latest workspace

[mine]
paths = [".env", ".env.*", "!.env.example", "!.env.sample", "!.env.template"]   # the default

[land]
run = ["pnpm lint", "pnpm test"]   # vcs land runs these in the workspace first; if one fails, nothing lands (vcs land --no-run skips them)
```

`[land] run` is this machine's, as git hooks are. Required checks, approvals and who can land are host settings, not file settings, so a change can't loosen its own rules.

## 13. Limits and targets

| | Target | Measured (Oct 27, `tests/perf.sh`, self-hosted server, one Linux machine) |
|---|---|---|
| `vcs status` on 20,000 files | under 100 ms | 66 ms |
| Second workspace of a 15,000-file project | under 2 s | 0.6 s |
| Land with no required checks, server time | under 50 ms | 0.5 ms median |
| Landings on one main | 400 or more per second | about 2,000 per second; 63 agents landing at once all landed in 1.2 s |
| A save showing up on another of your machines | under 5 s | not measured yet |
| One file | up to 5 GB, stored in chunks, so a small edit to a big file uploads only what changed | |
| One project | up to 100 GiB, the same as Upstream Rapid today | enforced by Upstream's host |

Against stock git (`tests/bench.sh` on one machine, git with a bare repository on the same disk; `tests/bench-live.sh` against git.coline.app and vcs.coline.dev; Oct 28):

| | git | vcs |
|---|---|---|
| `status`, 20,000 files | 16 ms | 54 ms |
| One change, commit + push vs land (same machine / live) | 0.07 s / 0.81 s | 0.12 s / 0.30 s |
| First copy, 20,000 files (same machine) / 275 files and 300 versions (live) | 1.26 s / 1.47 s | 0.98 s / 0.49 s |
| 8 / 32 / 64 agents landing on one branch (same machine) | 0.32 / 3.2 / 13.3 s, 1,960 pushes refused at 64 | 0.04 / 0.14 / 0.28 s, none refused |
| 16 agents landing on one branch (live) | 27.1 s, 107 pushes refused | 1.45 s, none refused |

Git's first copy carries all history; vcs fetches history when it's needed.

Upstream's host (`vcs.coline.dev`), measured Oct 28 from a machine in us-west-2:

| | Measured |
|---|---|
| `vcs land`, whole command | about 0.3 s (two requests) |
| 64 agents landing at once on one main | all 64 landed in 0.8 s |
| A fresh workspace of a small project | 0.23 s |
| A 15,000-file project: land, status, first workspace on a new machine | 0.28 s, 0.05 s, 4.6 s |
| `POST /edits` (landing without a workspace) | 0.15 s |
| The git view catching up 173 versions | 6 s, in batches of 64 per push |

Under load (`tests/load.mjs`, agents landing edits over HTTP as fast as they can, each to its own file; Oct 28):

| | Measured |
|---|---|
| 20 projects × 25 agents, 60 s, plus 40 readers | 184,268 landed, 3,052 a second; none failed; landing p50 141 ms, p99 579 ms; reads p50 138 ms |
| 20 projects × 75 agents (1,500 agents), 45 s | 4,094 landed a second, about 200 a second per project; none failed |
| One project, 256 agents | about 100 landed a second; none failed; each waits its turn (p50 2.2 s) |
| One project with its git view on, 64 agents | about 70 landed a second; the git view caught up 17 s after a 20 s burst (256 versions a push, about 2 s each to git.coline.app) |
| A version reaching the git view when the project is quiet | about 0.35 s |
| Host CPU a landing (Durable Object) | about 3 ms (it was 17 ms before edits stopped rebuilding the whole tree) |

A project is one Durable Object, so projects scale out; one project's landings are one queue.

At rest on Upstream's host, a project's objects in R2 are encrypted (AES-256 in counter mode, a key for each project derived from a host secret, so a byte range of a pack reads on its own; every object's ID is the SHA-256 of its content, so a changed byte can't pass as the object). That covers private folders and mine files with everything else; the host still reads them, since it merges and checks what lands. Small objects kept in the project's database are encrypted at rest by the platform. A project's packs from before encryption are written again encrypted as it's used.

Platforms: macOS, Linux and Windows (x64 and arm64 each). On Windows a file keeps the kind vcs knows it as (executable, link) when edited, as git does there, since the disk can't always say.

## 14. Not in this version

- Changing a submodule's commit from vcs (it changes in git and comes in with `vcs import --change`), and SHA-256 git views (Git 3.0).
- End-to-end encryption, where the host can't read private files: it merges and checks what lands, so it reads it.
- Lazy workspaces on macOS (FSKit) and Windows (ProjFS). On those, `--only` covers big projects for now.
- Release lines in each person's own git URL (it has main only), review rules for lines, and landing on a line at a set time or together with other projects.
- Undoing a landing on a release line (land a change that reverses it).
- Agent session transcripts.
- Editor integrations, and a git folder inside workspaces for editors' git panels.
- Package managers (Homebrew, winget, apt, npm): installs go through the install scripts. macOS builds are signed ad hoc, not notarized.

## 15. For implementers

- **Core** (`vcs/core`, Rust, no I/O):
  - Objects are blobs, chunk lists and trees, each named by SHA-256 of a kind byte and its data. Files over 1 MiB are split into content-defined chunks (FastCDC, 16 KiB to 256 KiB, about 64 KiB on average).
  - A tree is a sorted list of entries (kind, name, ID), and kinds are file, executable, link and folder.
  - A version records its number, tree, change, author, description, time and the previous version's hash, so main is a hash chain.
  - Merges are 3-way per file (histogram diff, git-style markers), with JSON merged by key. Private paths are filtered out of trees and grafted back when someone who can't see them lands.
  - Bundles carry objects between machines: `VCSB1` frames, zstd when it helps, each checked against its ID on arrival.
- **CLI** (`vcs/cli`): one Rust binary on the core. SQLite and one file per object under `VCS_HOME` (by default `~/.local/share/vcs`), shared by every workspace. The saver watches with FSEvents on macOS and inotify on Linux, and looks at active workspaces every 30 seconds for anything the watches missed. `VCS_TRACE=1` prints each call to the host with its status and time.
- **Protocol:** HTTPS with JSON control calls and bundle uploads and downloads (`vcs/cli/src/wire.rs` lists every call). A host names its API in `/.well-known/vcs.json`.
- **Self-hosted server** (`vcs/server`, `vcs-server`): the same protocol on SQLite and a folder of objects, with its own accounts and tokens. It has no git view.
- **Upstream's host** (`apps/vcs`, at `vcs.coline.dev`): a Cloudflare Worker with one Durable Object per project (SQLite for versions, changes, saves, rules and the object index) and objects in R2, where each upload is stored as it came and indexed by offset. A long history leaves a tree's files spread across many uploads, so the host keeps a snapshot of a recent tree's objects in one R2 object, as git hosts keep packs ready for clones: a new machine gets that snapshot plus what changed since (on a 20,000-version project, 1.4–2 s against 18 s). The core runs in it as Wasm (`vcs/wasm`) for merges, private paths and the git view. Accounts, roles and tokens are Upstream's, from its public API. The git view is written by pushing to the repository through `git.coline.app` with the lander's token, like any git client, so Upstream Rapid is unchanged.
- **Licenses:** the core, CLI and protocol are Apache-2.0, and `vcs-server` is AGPL.