123 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 approve <change>` approves someone else's change. If it was the last approval the project needs, it lands. |
| 75 | - `vcs access <change> @person` lets someone see your change. Add `--edit` to let them work on it. |
| 76 | - `vcs access <path or change>` with no names shows who can see it. |
| 77 |
| 78 | ## Fixing mistakes |
| 79 |
| 80 | - `vcs undo` undoes the last vcs command in this workspace. Run it again to go further back. |
| 81 | - It also undoes a land: main gets a new version that takes it back out, and the change reopens here. |
| 82 | - `vcs undo <version>` takes an older landed version back out of main without undoing anything else. |
| 83 | - `vcs restore <file>` puts a file back to how it was before your change. |
| 84 | - `--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. |
| 85 | - `--from <version>` takes the file from a version of main. |
| 86 | - 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. |
| 87 | - `vcs drop` abandons the current change. `vcs undo` brings it back. |
| 88 | - **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. |
| 89 |
| 90 | ## Rules |
| 91 |
| 92 | - **Descriptions:** the first line says what changed. Then say why, and what you checked (tests, build). |
| 93 | - Don't land other people's changes, pass `--allow-secrets`, change access, purge, or start release lines unless the user asks. |
| 94 | - Don't print or copy what's in `.env` files. They belong to the user. |
| 95 | - Add `--json` when you want to parse output. It has the same facts, plus `next`. |
| 96 |
| 97 | ## git → vcs |
| 98 |
| 99 | | User asks for | Run | |
| 100 | |---|---| |
| 101 | | `git status`, `git diff`, `git log` | `vcs status`, `vcs diff`, `vcs log` | |
| 102 | | `git log -- <file>`, `git blame <file>` | `vcs log <file>`, `vcs blame <file>` | |
| 103 | | `git show <rev>:<file>` | `vcs show <file> --from <version>` | |
| 104 | | pre-commit hooks | `[land] run` in `vcs.toml` | |
| 105 | | `git tag v1.0` | `vcs tag v1.0` | |
| 106 | | `git add`, `git commit` | Nothing: it's saved. Use `vcs describe "Title"` to set the description. | |
| 107 | | `git push`, "commit and push", "merge to main" | `vcs land -m "Title"` | |
| 108 | | `git pull`, `git fetch`, `git rebase main` | `vcs sync` | |
| 109 | | `git checkout -b`, a new branch | `vcs new "Title"` | |
| 110 | | `git switch`, `git checkout <branch>` | `vcs switch <change>` | |
| 111 | | `git stash` | `vcs new` (the current change stays saved) | |
| 112 | | `git checkout -- <file>`, `git restore <file>` | `vcs restore <file>` | |
| 113 | | `git reset`, `git reflog` to recover | `vcs undo`, or `vcs restore <file> --at "<time>"` | |
| 114 | | `git revert` | `vcs undo` right after landing, or `vcs undo <version>` for an older one | |
| 115 | | `git bisect` | `vcs bisect <good> <bad> --run "<command>"` | |
| 116 | | `git cherry-pick` onto a release branch | `vcs land <change> --to <line>` | |
| 117 | | `git filter-repo` to remove a file | `vcs purge <file>` (only when the user asks) | |
| 118 | | `git init` | `vcs init <folder>` | |
| 119 | | `git clone` | `vcs get <project> <folder>` | |
| 120 | | `git worktree add` | `vcs get <project> <folder>` | |
| 121 | | open a pull request | `vcs land` (if you can't land on your own, it asks the people who can) | |
| 122 | | merge a git branch someone pushed | `vcs import <git-url> --change <branch>`, then `vcs land` | |
| 123 |