# Work from a shared world

Start from the team's history, keep it fresh, and know what you are holding.

This page supplies an executable walkthrough for `packages/cli/src/journeys/tutorials.test.ts`.

## The shared world, for this page

The world from [share a world](./share-a-world.md), on this machine, with one issue in it.

```json file=package.json
{ "name": "acme-web", "private": true, "type": "module", "dependencies": { "@octokit/rest": "^21" } }
```

The app declares the credential it reads. The World issues a throwaway token for its GitHub account,
`world`; that account is separate from the platform org `acme`. The seed creates `world/web` through
Octokit before any issue is written. It can run again without creating a second repository.

```text file=.env.example
GITHUB_TOKEN=
```

```js file=.volter/seed.ts
import { Octokit } from '@octokit/rest';
const github = new Octokit({ auth: process.env.GITHUB_TOKEN });
const { data: { login: owner } } = await github.users.getAuthenticated();
try {
  await github.repos.get({ owner, repo: 'web' });
} catch (error) {
  if (error.status !== 404) throw error;
  await github.repos.createForAuthenticatedUser({ name: 'web' });
}
```

```js file=file-issue.mjs
import { Octokit } from '@octokit/rest';
const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
const { data: issue } = await octokit.issues.create({ owner: 'world', repo: 'web', title: process.argv[2] ?? 'Launch checklist' });
console.log(`filed #${issue.number}`);
```

```text file=../team/.env.example
GITHUB_TOKEN=
```

```js file=../team/.volter/seed.ts
import '../../acme-web/.volter/seed.ts';
```

```bash
npm install
npm install -g @volter/world
npm install -D @volter/twin-github
cd ../team && volter world init --bare acme/team --twins github
volter world up
volter world down
volter world serve --port 4300 &
```

With the shared World serving, clone its history into the app:

```bash
cd ../acme-web
volter world init
volter world clone http://127.0.0.1:4300/acme/team --token "$(cat ../team/.volter/token)"
volter world up
```

```text
cloned  http://127.0.0.1:4300/acme/team  14 changes
```

## Clone

`clone` records the shared world as origin, remembers the token in your config directory
(`~/.config/volter/credentials.json`, owner-only, keyed by the URL), and sets your base to the
shared world's current position. Your world's history is the team's from here on.
The cloned history includes the shared account and repository setup, before the app files its first issue.

```bash
volter world origin
```

```text
origin  http://127.0.0.1:4300/acme/team
```

## Pull

Someone else pushes. `pull` brings it in and moves your base; your own entries stay on top.

```bash
cd ../team && volter world run -- node ../acme-web/file-issue.mjs "From the shared world" && cd ../acme-web
volter world pull
volter world log
```

```text
pulled  origin  2 changes
github   issue.opened   issue:1
```

Pull before a push, and pull whenever you want the world to look like the team's does now.

## Branch over the shared history

A branch starts at your current position, which is now the team's history. Work on it, compare,
and come back.

```bash
volter world branch spike
volter world run -- node file-issue.mjs "Spike"
volter world diff
volter world checkout main
volter world diff
```

```text
filed #2
2 changes since branch spike
0 changes since origin
```

## What you are holding

If the shared world's twins have a root at the vendor, the history you cloned is real records from
a real account, in plain text on your disk. Treat it that way: do not commit it, do not paste it
into a bug report, and `volter world reset` or `volter world down --purge` when the session that
needed it ends. [Data and keys](../concepts/data-and-keys.md) says exactly what lands where.

## Back to the default data

A world with an origin can still reset. The branch returns to the default data; the origin stays
recorded, and the next `pull` brings the team's history back.
The scratch branch created above references that history. Once you have finished with the scratch branch, discard
its retained state before resetting its parent. The following commands discard the scratch work and local changes.

```bash
volter world down --branch spike --purge
volter world reset
volter world origin
volter world down
kill %1
```

```text
origin  http://127.0.0.1:4300/acme/team
```