# Onset for teams on git

Every project on Upstream is also a git repository, so a team can try Onset 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
on import upstream.codes/acme/shop --to upstream.codes/acme/shop
```

This makes the repository an Onset project in place (you need to be one of its admins). Its git history stays exactly as it was, commit for commit; main becomes Onset's main, and each new version is pushed back to git main as a commit within seconds. From then on:

```sh
on get upstream.codes/acme/shop        # a workspace
# ...edit...
on 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: `on 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 Onset land. Both end up on the same main.

- **A git push to main comes into Onset** 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 Onset 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 Onset, a force push, or more than 32 MB at once), the git view pauses rather than overwrite anything, and `on git` says why. Bring the git side in with `on import <git url> --change main`, land it, then `on git resume`.
- **Git branches come in as changes:** `on import <git url> --change <branch>` in a workspace makes the branch a change on top of the version it started from, ready for `on land`.
- **Commits from Onset say where they came from:** each ends with `Onset-Change: <id>` and `Onset-Version: <n>` (`Vcs-Change` and `Vcs-Version` on commits from before Onset had its name).
- **Private paths stay out of git.** A folder made private in Onset (`on 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.

## Keeping GitHub (or GitLab, or your own git server)

A team whose pull requests and CI live on GitHub can land with Onset and keep GitHub as it is:

```sh
on import https://github.com/acme/shop --to upstream.codes/acme/shop   # or on init / on publish to your own onset-server
on git mirror https://github.com/acme/shop                              # keeps GitHub's main as Onset's main, both ways
```

Every version of main becomes a commit on GitHub's `main` (same message and author, with `Onset-Version` and `Onset-Change` trailers), pushed with your own git credentials. A pull request merged on GitHub comes into Onset's main as a version, merged with whatever landed meanwhile, and GitHub gets a merge commit joining both lines. Run it on any machine with landing rights (a CI runner, a small server): it keeps going until stopped, or `--once` from a scheduled job. If both sides changed the same lines, or someone force-pushes GitHub's main, it stops and says so rather than overwrite anything.

## Moving over

When everyone is on Onset, `on settings git=off` stops copying main to git. `on 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 Onset |
|---|---|
| `git clone` | `on 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 | `on land`: the server merges with whatever landed since, in order |
| a branch per task | a change per task (`on new`), or a workspace per agent (`on workspaces add`) |
| `git stash` | `on new`; the change you left stays saved |
| `git reflog` | `on undo`, `on 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 |

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