Skip to main content

Working on a Cauldron deck with git

Every Cauldron deck has its own git repository on Castle. The Cauldron editor keeps it up to date as you work. You can clone it to your own computer, work with your own tools, and push your changes back. The editor picks them up while the deck is open.

In the editor​

You don't need to do anything to use it. A deck's repository starts the first time its creator opens it in the editor, and from then on the editor commits the deck's changes to it:

  • when Operator finishes a turn or a task,
  • and when you leave the deck.

Changes you make by hand go into the next commit along with Operator's.

Files → Version history lists those commits, newest first, with who made each one. Restore adds a new commit that puts the deck back the way it was at that version. It never deletes history, so you can always move forward again.

On your computer​

You need Node.js, git and the castle-web command-line tool (see Local development). Signing in with castle-web login also lets git use your Castle login for Castle's git server, so you don't need a separate password or key.

npm install -g castle-web-cli
castle-web login

Clone a deck​

castle-web git clone <deckId>

You can also pass the deck's editor link (https://castle.xyz/create/<deckId>) or its git URL, https://git.castle.xyz/<deckId>.git. In the clone, the remote is named castle. If the deck's repository has no history yet, open the deck in the editor once first, or start it from your computer (see below).

Some of a deck isn't stored in the repository (see below), so restore it first. Then work as you would in any git repository:

cd <deck folder>
castle-web install # restores the deck's imports and npm dependencies
git commit -am "Faster jumps"
git push castle main

To try the deck locally while you work, run castle-web serve --detach. It starts Castle's Play, Files and Parameters panels in the background and prints their URL.

If the deck is open in the editor, your push usually shows up there within half a minute, without reloading. While Operator is working, the editor waits until it has finished. If the deck isn't open, your push is there the next time you open it. To get the editor's latest changes, run git pull castle main.

Connect a deck you already have​

To connect a deck folder that you made with castle-web init, run this inside it:

castle-web git init
git add -A
git commit -m "First version"
git push castle main

git init connects the folder to the deck in its castle.json (creating the deck on Castle if it doesn't have one yet), and adds the castle remote. The next time you open the deck in the editor, it takes the version you pushed. If the editor had its own copy of the deck, it keeps a backup of the files that differed, and Operator checks whether any of them are worth carrying over.

This is for a deck whose repository is still empty. If the deck already has history on Castle, because it's been opened in the editor since it got its repository, clone it instead.

How the editor and your computer stay in step​

  • The editor works only on main. As the deck's creator you can push other branches and tags too, but the editor ignores them.
  • The editor never force-pushes. If you push while Operator is working, the editor waits until it has finished, then merges your changes in.
  • If both sides changed the same lines, Operator resolves the conflict itself, keeps your pushed changes where it can, and tells you in the chat what it did.
  • Don't rewrite main's history. If you force-push main from your computer (only the deck's creator can), for example to drop a file you committed by mistake, the editor merges the history it already has back in the next time it syncs. To undo a change, commit the fix on top instead.

What isn't in the repository​

The editor's commits leave out what can be rebuilt: node_modules/, dist/, imports/ (the other decks and kits your deck imports, restored from castle.json), .castle/ (local state), and npm, pnpm, yarn and bun lockfiles. If a commit from your computer includes node_modules/ or a lockfile, the editor stops tracking them in its next commit and keeps its own copies on disk. After you clone, castle-web install restores the imports and installs the npm dependencies.

Limits​

  • A single push can be at most 256 MB. If the editor's changes waiting to upload are over that, it says so in the chat, names the largest new files when there are any, and waits at least half an hour before trying again. Your files and drafts are fine, but the deck's history on Castle stays behind until the waiting changes fit. Keep large media small, and remove files the deck doesn't use.
  • A deck's repository is private to the people who can edit the deck: whatever the deck's visibility, nobody else can clone it or push to it.

Git and publishing​

Pushing to the repository doesn't publish your deck. To put a new version on Castle, use Push to Castle in the editor (Save in the app), or castle-web save-deck from your computer. See Getting started.

Back to What is Cauldron?