# 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` | Read the log link, fix the problem, then `vcs land` again. | | 5 | `waiting` | A person has to land it. 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. - **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. ## 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 status ` shows any change, including whether it landed. ## 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 full history. - 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 @group` makes a folder or file visible only to that group (and `@person` for one person, `me` for only the user). - `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. - `--from ` takes the file from a version of main. - `vcs drop` abandons the current change. `vcs undo` brings it back. ## 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`, or change access 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 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 "