106 lines · 7 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), or a host check. Fix the problem, then `vcs land` again. | |
| 28 | | 5 | `waiting` | A person has to land or approve it. 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 |
| 42 | ## Looking around |
| 43 |
| 44 | - `vcs diff` shows what your change changes (`--stat` for a summary). |
| 45 | - `vcs log` shows recent versions of main. `vcs log --changes` shows open changes and who has them. |
| 46 | - `vcs log <path>` shows the versions that changed a file or folder. `vcs blame <file>` shows which version last changed each line. `vcs show <file> --from <version>` prints a file as it was. |
| 47 | - `vcs status <id>` shows any change, including whether it landed. |
| 48 |
| 49 | ## Starting a project |
| 50 |
| 51 | - `vcs init <folder>` starts a new project that lives only on this machine. Landing works locally. |
| 52 | - `vcs publish upstream.codes/<owner>/<name>` puts a local project on the host, keeping its history. |
| 53 | - `vcs import <git-url> --to upstream.codes/<owner>/<name>` makes a project from a git or GitHub repository, with its history. |
| 54 | - `vcs import <git-url> --change <branch>` brings a git branch into this workspace's project as a change, ready for `vcs land`. |
| 55 | - `vcs git` shows the git URL the project clones from. |
| 56 | - 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. |
| 57 |
| 58 | ## Sharing and access |
| 59 |
| 60 | Only run these when the user asks. |
| 61 | - `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). |
| 62 | - `vcs approve <change>` approves someone else's change. If it was the last approval the project needs, it lands. |
| 63 | - `vcs access <change> @person` lets someone see your change. Add `--edit` to let them work on it. |
| 64 | - `vcs access <path or change>` with no names shows who can see it. |
| 65 |
| 66 | ## Fixing mistakes |
| 67 |
| 68 | - `vcs undo` undoes the last vcs command in this workspace. Run it again to go further back. |
| 69 | - It also undoes a land: main gets a new version that takes it back out, and the change reopens here. |
| 70 | - `vcs undo <version>` takes an older landed version back out of main without undoing anything else. |
| 71 | - `vcs restore <file>` puts a file back to how it was before your change. |
| 72 | - `--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. |
| 73 | - `--from <version>` takes the file from a version of main. |
| 74 | - 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. |
| 75 | - `vcs drop` abandons the current change. `vcs undo` brings it back. |
| 76 |
| 77 | ## Rules |
| 78 |
| 79 | - **Descriptions:** the first line says what changed. Then say why, and what you checked (tests, build). |
| 80 | - Don't land other people's changes, pass `--allow-secrets`, or change access unless the user asks. |
| 81 | - Don't print or copy what's in `.env` files. They belong to the user. |
| 82 | - Add `--json` when you want to parse output. It has the same facts, plus `next`. |
| 83 |
| 84 | ## git → vcs |
| 85 |
| 86 | | User asks for | Run | |
| 87 | |---|---| |
| 88 | | `git status`, `git diff`, `git log` | `vcs status`, `vcs diff`, `vcs log` | |
| 89 | | `git log -- <file>`, `git blame <file>` | `vcs log <file>`, `vcs blame <file>` | |
| 90 | | `git show <rev>:<file>` | `vcs show <file> --from <version>` | |
| 91 | | pre-commit hooks | `[land] run` in `vcs.toml` | |
| 92 | | `git add`, `git commit` | Nothing: it's saved. Use `vcs describe "Title"` to set the description. | |
| 93 | | `git push`, "commit and push", "merge to main" | `vcs land -m "Title"` | |
| 94 | | `git pull`, `git fetch`, `git rebase main` | `vcs sync` | |
| 95 | | `git checkout -b`, a new branch | `vcs new "Title"` | |
| 96 | | `git switch`, `git checkout <branch>` | `vcs switch <change>` | |
| 97 | | `git stash` | `vcs new` (the current change stays saved) | |
| 98 | | `git checkout -- <file>`, `git restore <file>` | `vcs restore <file>` | |
| 99 | | `git reset`, `git reflog` to recover | `vcs undo`, or `vcs restore <file> --at "<time>"` | |
| 100 | | `git revert` | `vcs undo` right after landing, or `vcs undo <version>` for an older one | |
| 101 | | `git init` | `vcs init <folder>` | |
| 102 | | `git clone` | `vcs get <project> <folder>` | |
| 103 | | `git worktree add` | `vcs get <project> <folder>` | |
| 104 | | open a pull request | `vcs land` (if you can't land on your own, it asks the people who can) | |
| 105 | | merge a git branch someone pushed | `vcs import <git-url> --change <branch>`, then `vcs land` | |
| 106 |