Onset: version control where nobody waits and nothing gets lost. The on command, its core and onset-server.
| 1 | # vcs for teams on git |
| 2 | |
| 3 | Every project on Upstream is also a git repository, so a team can try vcs without anyone else changing anything, use both for as long as it likes, or move over completely. Nothing about git stops working: clones, pull requests from forks, CI, GitHub mirrors. |
| 4 | |
| 5 | ## Try it on a repository you already have |
| 6 |
| 7 | ```sh |
| 8 | vcs import upstream.codes/acme/shop --to upstream.codes/acme/shop |
| 9 | ``` |
| 10 |
| 11 | This makes the repository a vcs project in place (you need to be one of its admins). Its git history stays exactly as it was, commit for commit; main becomes vcs's main, and each new version is pushed back to git main as a commit within seconds. From then on: |
| 12 |
| 13 | ```sh |
| 14 | vcs get upstream.codes/acme/shop # a workspace |
| 15 | # ...edit... |
| 16 | vcs land -m "Fix the login redirect" # merged into main on the server, never refused |
| 17 | ``` |
| 18 |
| 19 | A repository somewhere else (GitHub, a folder) works the same way: `vcs import <git url> --to upstream.codes/you/name` makes a new project with its history. |
| 20 |
| 21 | ## Using both |
| 22 |
| 23 | People on git keep pushing to main as usual; people and agents on vcs land. Both end up on the same main. |
| 24 |
| 25 | - **A git push to main comes into vcs** within seconds: each commit on main's first-parent line becomes a version, with its message and author, and the version is that same commit in git. If vcs landed something meanwhile, the git commits merge into one version, and git gets a merge commit joining both lines. Nobody's work is overwritten. |
| 26 | - **When they can't merge by themselves** (both sides changed the same lines, a commit touches a folder that's private in vcs, a force push, or more than 32 MB at once), the git view pauses rather than overwrite anything, and `vcs git` says why. Bring the git side in with `vcs import <git url> --change main`, land it, then `vcs git resume`. |
| 27 | - **Git branches come in as changes:** `vcs import <git url> --change <branch>` in a workspace makes the branch a change on top of the version it started from, ready for `vcs land`. |
| 28 | - **Commits from vcs say where they came from:** each ends with `Vcs-Change: <id>` and `Vcs-Version: <n>`. |
| 29 | - **Private paths stay out of git.** A folder made private in vcs (`vcs access billing/ @sam`) is left out of the git view for everyone, so people who only use git never see it, and their pushes can't change it. |
| 30 |
| 31 | ## Moving over |
| 32 |
| 33 | When everyone is on vcs, `vcs settings git=off` stops copying main to git. `vcs settings git=on` turns it back on later and catches it up (and brings in anything pushed to git meanwhile). |
| 34 |
| 35 | ## What changes for people |
| 36 |
| 37 | | On git | On vcs | |
| 38 | |---|---| |
| 39 | | `git clone` | `vcs get` (a workspace on a new change) | |
| 40 | | `git add`, `git commit` | nothing: every command saves, and so does the background saver | |
| 41 | | `git pull --rebase`, `git push`, retry | `vcs land`: the server merges with whatever landed since, in order | |
| 42 | | a branch per task | a change per task (`vcs new`), or a workspace per agent (`vcs workspaces add`) | |
| 43 | | `git stash` | `vcs new`; the change you left stays saved | |
| 44 | | `git reflog` | `vcs undo`, `vcs restore --at "10 min ago"` | |
| 45 | | `.gitignore` | the same file, the same rules | |
| 46 | | `.env` kept out by `.gitignore` | `.env` files are yours: saved, follow you to new workspaces, never land | |
| 47 |
| 48 | `vcs guide` prints the same in a form written for coding agents. |
| 49 |
