# Using vcs (guide for coding agents) This project uses **vcs** for version control, not git. A vcs workspace has no `.git` folder, so git commands don't work here. Use the commands below. If the user asks for a git command, do the vcs equivalent from the table at the end. ## How it works - **Your work is a change.** A change has an ID made of letters (`rtnbkcvx`; the first 4 or more letters are enough). It saves itself: every vcs command saves first, and edits are saved within seconds. There's no staging and no commit. - **main is the shared line.** It moves in numbered versions (main 48213). Numbers are always versions and letters are always changes. - **`vcs land` puts your change on main.** The server merges it with whatever landed since you started, so don't pull, sync or rebase first. - **A workspace is a folder working on one change.** Use one workspace per task, and never edit files in a folder another agent is using. ## The loop 1. `vcs status` shows where you are. 2. Edit files. 3. `vcs land -m "Title" -m "Why: … Checked: …"` lands the change. Afterwards you're on a new, empty change and your files are unchanged. Every command ends with a `next:` line. When unsure, do what it says. ## When land doesn't go through Read the exit code or `error.code`: | Exit | Code | Do this | |---|---|---| | 3 | `conflict` | Run `vcs sync`. Fix every file it lists by removing the `<<<<<<<` / `=======` / `>>>>>>>` markers and keeping the right code, then `vcs land` again. | | 4 | `checks_failed` | A check failed: one of `vcs.toml`'s `[land] run` commands (its output is above). Fix the problem, then `vcs land` again. | | 5 | `waiting` | A person has to land or approve it, or it's in review (a change request link is printed; it lands once its approvals and checks pass). Tell the user and stop. Don't retry in a loop. | | 8 | `secret` | Remove the secret from that line. Real secrets go in `.env`, which only the user can see. Never pass `--allow-secrets` unless the user tells you to. | | 6 | `offline` | Your change is saved. Try `vcs land` again later. | | 2 | `no_description` | Add `-m "Title"` and run it again. | ## Working in parallel - **A separate task:** `vcs get `, then work only in that folder. From inside a workspace, `vcs workspaces add ` does the same without naming the project. - **Handing part of your work to a subagent:** `vcs workspaces add --on .` makes a workspace on a new change that starts from yours as it is now. The subagent works and lands only there; landing it lands your change first. - **Cleaning up:** `vcs workspaces` lists this project's workspaces on the machine. `vcs workspaces clean` removes the ones whose work is done: each is saved first, and goes only if its change is then empty, no vcs command is running in it and nothing in it changed for 2 hours (`--idle 10m` for less). Work that hasn't landed is never removed. - **Another task in the same folder:** `vcs new "Title"`. The current change stays saved, and `vcs switch ` goes back to it. - **Building on a change that hasn't landed:** `vcs new "Title" --on `. Landing the new change lands both, in order. - **Picking up a change from another machine or agent:** `vcs get --change `, or `vcs switch ` in a workspace you already have. - **Changes in two projects that must land together** (an API and its client): `vcs land -m "Title" --with ../other-workspace`. Both land, or neither does. Give the other workspace's change a description first (`vcs -C ../other-workspace describe "Title"`). - **Landing later:** `vcs land -m "Title" --at "fri 9:00"` (or `"in 2h"`). Only when the user asks for a time. - **A big project:** `vcs get --lazy` (Linux) shows every file at once and fetches each one the first time it's opened. Work there as in any workspace. If the folder looks empty after a restart, `vcs mount ` (or any vcs command run in it) brings it back. ## Release lines - `vcs line` lists the project's release lines (like `1.x`, kept next to main). Start one only when the user asks: `vcs line 1.x --from v1.0`. - **A fix for a line:** `vcs get --line 1.x` (or `vcs new "Title" --line 1.x`), edit, `vcs land`: it lands on 1.x. - **A fix that landed on main, for a line too:** `vcs land --to 1.x`. If it conflicts there, you're put on a new change on 1.x with the conflicts marked: fix them, then `vcs land`. - `vcs log --line 1.x` shows a line's versions; `1.x/3` names its version 3 wherever a version goes (`vcs show --from 1.x/3`). ## Looking around - `vcs diff` shows what your change changes (`--stat` for a summary). - `vcs log` shows recent versions of main. `vcs log --changes` shows open changes and who has them. - `vcs log ` shows the versions that changed a file or folder, following it back through moves. `vcs blame ` shows which version last changed each line. `vcs show --from ` prints a file as it was. - `vcs status ` shows any change, including whether it landed. - **Finding what broke something:** `vcs bisect --run ""` tries versions in a folder of its own (your files don't change) and prints the first bad one. The command exits 0 for good, 125 to skip a version it can't judge, anything else for bad. - `vcs verify [version]` says who signed the land that made a version (exit 1 if it wasn't signed or doesn't check out). ## Starting a project - `vcs init ` starts a new project that lives only on this machine. Landing works locally. - `vcs publish upstream.codes//` puts a local project on the host, keeping its history. - `vcs import --to upstream.codes//` makes a project from a git or GitHub repository, with its history. - `vcs import --change ` brings a git branch into this workspace's project as a change, ready for `vcs land`. - `vcs git` shows the git URL the project clones from. - If a command says you're not signed in (exit 7), tell the user to run `vcs login`. Agents get a `VCS_TOKEN` from the user and never ask for passwords. ## Sharing and access Only run these when the user asks. - `vcs access @person` makes a folder or file visible only to that person (`@group` for one of the project's groups, `me` for only the user). - `vcs approve ` approves someone else's change. If it was the last approval the project needs, it lands. - `vcs access @person` lets someone see your change. Add `--edit` to let them work on it. - `vcs access ` with no names shows who can see it. ## Fixing mistakes - `vcs undo` undoes the last vcs command in this workspace. Run it again to go further back. - It also undoes a land: main gets a new version that takes it back out, and the change reopens here. - `vcs undo ` takes an older landed version back out of main without undoing anything else. - `vcs restore ` puts a file back to how it was before your change. - `--at "10 min ago"` brings back an earlier save of your own work. `vcs log --saves` lists the saves, and `--from :` takes the file from one of them. - `--from ` takes the file from a version of main. - A change taken back out of main reopens, so nothing is lost. `vcs log --changes` lists it; `vcs drop ` if it's not wanted. - `vcs drop` abandons the current change. `vcs undo` brings it back. - **A secret or a huge file that landed:** tell the user. Only if they ask, `vcs purge ` shows what taking it out of the whole history would do, and `vcs purge --yes` does it (owners only; it can't be undone, rewrites the git view's main, and deletes the file here too). A leaked secret still has to be changed. ## Rules - **Descriptions:** the first line says what changed. Then say why, and what you checked (tests, build). - Don't land other people's changes, pass `--allow-secrets`, change access, purge, or start release lines unless the user asks. - Don't print or copy what's in `.env` files. They belong to the user. - Add `--json` when you want to parse output. It has the same facts, plus `next`. ## git → vcs | User asks for | Run | |---|---| | `git status`, `git diff`, `git log` | `vcs status`, `vcs diff`, `vcs log` | | `git log -- `, `git blame ` | `vcs log `, `vcs blame ` | | `git show :` | `vcs show --from ` | | pre-commit hooks | `[land] run` in `vcs.toml` | | `git tag v1.0` | `vcs tag v1.0` | | `git add`, `git commit` | Nothing: it's saved. Use `vcs describe "Title"` to set the description. | | `git push`, "commit and push", "merge to main" | `vcs land -m "Title"` | | `git pull`, `git fetch`, `git rebase main` | `vcs sync` | | `git checkout -b`, a new branch | `vcs new "Title"` | | `git switch`, `git checkout ` | `vcs switch ` | | `git stash` | `vcs new` (the current change stays saved) | | `git checkout -- `, `git restore ` | `vcs restore ` | | `git reset`, `git reflog` to recover | `vcs undo`, or `vcs restore --at "