128 lines · 10 KBtext/plain; charset=utf-8
Onset: version control where nobody waits and nothing gets lost. The on command, its core and onset-server.
| ## How it works |
| 6 |
| 7 | - **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. |
| 8 | - **main is the shared line.** It moves in numbered versions (main 48213). Numbers are always versions and letters are always changes. |
| 9 | - **`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. |
| 10 | - **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. |
| 11 |
| 12 | ## The loop |
| 13 |
| 14 | 1. `vcs status` shows where you are. |
| 15 | 2. Edit files. |
| 16 | 3. `vcs land -m "Title" -m "Why: … Checked: …"` lands the change. Afterwards you're on a new, empty change and your files are unchanged. |
| 17 |
| 18 | Every command ends with a `next:` line. When unsure, do what it says. |
| 19 |
| 20 | ## When land doesn't go through |
| 21 |
| 22 | Read the exit code or `error.code`: |
| 23 |
| 24 | | Exit | Code | Do this | |
| 25 | |---|---|---| |
| 26 | | 3 | `conflict` | Run `vcs sync`. Fix every file it lists by removing the `<<<<<<<` / `=======` / `>>>>>>>` markers and keeping the right code, then `vcs land` again. | |
| 27 | | 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. | |
| 28 | | 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. | |
| 29 | | 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. | |
| 30 | | 6 | `offline` | Your change is saved. Try `vcs land` again later. | |
| 31 | | 2 | `no_description` | Add `-m "Title"` and run it again. | |
| 32 |
| 33 | ## Working in parallel |
| 34 |
| 35 | - **A separate task:** `vcs get <project> <new-folder>`, then work only in that folder. From inside a workspace, `vcs workspaces add <new-folder>` does the same without naming the project. |
| 36 | - **Handing part of your work to a subagent:** `vcs workspaces add <new-folder> --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. |
| 37 | - **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. |
| 38 | - **Another task in the same folder:** `vcs new "Title"`. The current change stays saved, and `vcs switch <id>` goes back to it. |
| 39 | - **Building on a change that hasn't landed:** `vcs new "Title" --on <id>`. Landing the new change lands both, in order. |
| 40 | - **Picking up a change from another machine or agent:** `vcs get <project> <folder> --change <id>`, or `vcs switch <id>` in a workspace you already have. |
| 41 | - **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"`). |
| 42 | - **Landing later:** `vcs land -m "Title" --at "fri 9:00"` (or `"in 2h"`). Only when the user asks for a time. |
| 43 | - **A big project:** `vcs get <project> <folder> --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 <folder>` (or any vcs command run in it) brings it back. |
| 44 |
| 45 | ## Release lines |
| 46 |
| 47 | - `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`. |
| 48 | - **A fix for a line:** `vcs get <project> <folder> --line 1.x` (or `vcs new "Title" --line 1.x`), edit, `vcs land`: it lands on 1.x. |
| 49 | - **A fix that landed on main, for a line too:** `vcs land <change> --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`. |
| 50 | - `vcs log --line 1.x` shows a line's versions; `1.x/3` names its version 3 wherever a version goes (`vcs show <file> --from 1.x/3`). |
| 51 |
| 52 | ## Looking around |
| 53 |
| 54 | - `vcs diff` shows what your change changes (`--stat` for a summary). |
| 55 | - `vcs log` shows recent versions of main. `vcs log --changes` shows open changes and who has them. |
| 56 | - `vcs log <path>` shows the versions that changed a file or folder, following it back through moves. `vcs blame <file>` shows which version last changed each line. `vcs show <file> --from <version>` prints a file as it was. |
| 57 | - `vcs status <id>` shows any change, including whether it landed. |
| 58 | - **Finding what broke something:** `vcs bisect <good-version> <bad-version> --run "<test command>"` 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. |
| 59 | - `vcs verify [version]` says who signed the land that made a version (exit 1 if it wasn't signed or doesn't check out). |
| 60 |
| 61 | ## Starting a project |
| 62 |
| 63 | - `vcs init <folder>` starts a new project that lives only on this machine. Landing works locally. |
| 64 | - `vcs publish upstream.codes/<owner>/<name>` puts a local project on the host, keeping its history. |
| 65 | - `vcs import <git-url> --to upstream.codes/<owner>/<name>` makes a project from a git or GitHub repository, with its history. |
| 66 | - `vcs import <git-url> --change <branch>` brings a git branch into this workspace's project as a change, ready for `vcs land`. |
| 67 | - `vcs git` shows the git URL the project clones from. |
| 68 | - 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. |
| 69 |
| 70 | ## Sharing and access |
| 71 |
| 72 | Only run these when the user asks. |
| 73 | - `vcs access <path> @person` makes a folder or file visible only to that person (`@group` for one of the project's groups, `me` for only the user). |
| 74 | - `vcs access <folder> @person --sealed` also encrypts it on their machines, so the host can't read it. A sealed file that conflicts is merged by `vcs sync`, not the host. |
| 75 | - `vcs approve <change>` approves someone else's change. If it was the last approval the project needs, it lands. |
| 76 | - `vcs access <change> @person` lets someone see your change. Add `--edit` to let them work on it. |
| 77 | - `vcs access <path or change>` with no names shows who can see it. |
| 78 |
| 79 | ## Fixing mistakes |
| 80 |
| 81 | - `vcs undo` undoes the last vcs command in this workspace. Run it again to go further back. |
| 82 | - It also undoes a land: main gets a new version that takes it back out, and the change reopens here. |
| 83 | - `vcs undo <version>` takes an older landed version back out of main without undoing anything else. |
| 84 | - `vcs restore <file>` puts a file back to how it was before your change. |
| 85 | - `--at "10 min ago"` brings back an earlier save of your own work. `vcs log --saves` lists the saves, and `--from <change>:<save>` takes the file from one of them. |
| 86 | - `--from <version>` takes the file from a version of main. |
| 87 | - A change taken back out of main reopens, so nothing is lost. `vcs log --changes` lists it; `vcs drop <change>` if it's not wanted. |
| 88 | - `vcs drop` abandons the current change. `vcs undo` brings it back. |
| 89 | - **A secret or a huge file that landed:** tell the user. Only if they ask, `vcs purge <path>` shows what taking it out of the whole history would do, and `vcs purge <path> --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. |
| 90 |
| 91 | ## Your session |
| 92 |
| 93 | When you land, your session since your last land (what you were asked, what you said and ran) is kept with the change, secrets removed, for the user only. If the user asks to stop it, run `vcs sessions off`; to remove what was kept, `vcs sessions delete --all`. `vcs sessions show <change>` shows what was kept. |
| 94 |
| 95 | ## Rules |
| 96 |
| 97 | - **Descriptions:** the first line says what changed. Then say why, and what you checked (tests, build). |
| 98 | - Don't land other people's changes, pass `--allow-secrets`, change access, purge, or start release lines unless the user asks. |
| 99 | - Don't print or copy what's in `.env` files. They belong to the user. |
| 100 | - Add `--json` when you want to parse output. It has the same facts, plus `next`. |
| 101 |
| 102 | ## git → vcs |
| 103 |
| 104 | | User asks for | Run | |
| 105 | |---|---| |
| 106 | | `git status`, `git diff`, `git log` | `vcs status`, `vcs diff`, `vcs log` | |
| 107 | | `git log -- <file>`, `git blame <file>` | `vcs log <file>`, `vcs blame <file>` | |
| 108 | | `git show <rev>:<file>` | `vcs show <file> --from <version>` | |
| 109 | | pre-commit hooks | `[land] run` in `vcs.toml` | |
| 110 | | `git tag v1.0` | `vcs tag v1.0` | |
| 111 | | `git add`, `git commit` | Nothing: it's saved. Use `vcs describe "Title"` to set the description. | |
| 112 | | `git push`, "commit and push", "merge to main" | `vcs land -m "Title"` | |
| 113 | | `git pull`, `git fetch`, `git rebase main` | `vcs sync` | |
| 114 | | `git checkout -b`, a new branch | `vcs new "Title"` | |
| 115 | | `git switch`, `git checkout <branch>` | `vcs switch <change>` | |
| 116 | | `git stash` | `vcs new` (the current change stays saved) | |
| 117 | | `git checkout -- <file>`, `git restore <file>` | `vcs restore <file>` | |
| 118 | | `git reset`, `git reflog` to recover | `vcs undo`, or `vcs restore <file> --at "<time>"` | |
| 119 | | `git revert` | `vcs undo` right after landing, or `vcs undo <version>` for an older one | |
| 120 | | `git bisect` | `vcs bisect <good> <bad> --run "<command>"` | |
| 121 | | `git cherry-pick` onto a release branch | `vcs land <change> --to <line>` | |
| 122 | | `git filter-repo` to remove a file | `vcs purge <file>` (only when the user asks) | |
| 123 | | `git init` | `vcs init <folder>` | |
| 124 | | `git clone` | `vcs get <project> <folder>` | |
| 125 | | `git worktree add` | `vcs get <project> <folder>` | |
| 126 | | open a pull request | `vcs land` (if you can't land on your own, it asks the people who can) | |
| 127 | | merge a git branch someone pushed | `vcs import <git-url> --change <branch>`, then `vcs land` | |
| 128 |