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 pageCopy Anchor Link

The world from share a world, on this machine, with one issue in it.

{ "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.

GITHUB_TOKEN=

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' });
}

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}`);

GITHUB_TOKEN=

import '../../acme-web/.volter/seed.ts';

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:

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

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

CloneCopy Anchor Link

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.

volter world origin

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

PullCopy Anchor Link

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

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

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 historyCopy Anchor Link

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

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

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

What you are holdingCopy Anchor Link

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 says exactly what lands where.

Back to the default dataCopy Anchor Link

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.

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

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