# vcs for teams on git

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.

## Try it on a repository you already have

```sh
vcs import upstream.codes/acme/shop --to upstream.codes/acme/shop
```

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:

```sh
vcs get upstream.codes/acme/shop       # a workspace
# ...edit...
vcs land -m "Fix the login redirect"   # merged into main on the server, never refused
```

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.

## Using both

People on git keep pushing to main as usual; people and agents on vcs land. Both end up on the same main.

- **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.
- **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`.
- **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`.
- **Commits from vcs say where they came from:** each ends with `Vcs-Change: <id>` and `Vcs-Version: <n>`.
- **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.

## Moving over

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).

## What changes for people

| On git | On vcs |
|---|---|
| `git clone` | `vcs get` (a workspace on a new change) |
| `git add`, `git commit` | nothing: every command saves, and so does the background saver |
| `git pull --rebase`, `git push`, retry | `vcs land`: the server merges with whatever landed since, in order |
| a branch per task | a change per task (`vcs new`), or a workspace per agent (`vcs workspaces add`) |
| `git stash` | `vcs new`; the change you left stays saved |
| `git reflog` | `vcs undo`, `vcs restore --at "10 min ago"` |
| `.gitignore` | the same file, the same rules |
| `.env` kept out by `.gitignore` | `.env` files are yours: saved, follow you to new workspaces, never land |

`vcs guide` prints the same in a form written for coding agents.