# wip and main: the Two-Branch Model

> Why Edit Mode pushes to a wip branch on every checkpoint, how that differs from a publish, and what lives on each branch at any given moment.

- Source: https://diceytable.com/docs/mods/publishing/wip-and-main
- Last verified: 2026-07-27

Edit Mode never pushes directly to a mod's default branch while you're working. It
uses two branches with different purposes:

| Branch | Written by | Meaning |
|---|---|---|
| `wip` | every checkpoint, and the first step of every publish | your latest work-in-progress, always up to date, never automatically playable |
| `main` | only a publish's merge step | the live, playable version everyone else's client loads |

## Auto-checkpoint: debounced and incremental

While a mod is dirty (has unsaved changes) and linked to a repository, the editor
starts a ten-second timer after your last edit. When it fires, it pushes a checkpoint
commit to `wip`. Further edits within that window restart the timer, so a long editing
session collapses into occasional checkpoints rather than a commit per change.

Checkpoints are **incremental by content**, not just by intent: the editor hashes every
file in your local working tree and compares it against the hashes recorded at the last
successful push. Only files whose content actually changed are sent as bytes; the
*full* current list of asset paths is still sent alongside them so the manifest stays
complete, but unchanged assets are retained on the branch through GitHub's tree API
rather than re-uploaded. This keeps a checkpoint of a large mod cheap even when only one
texture changed.

If a checkpoint push fails, the status line says so and promises a retry — and that
retry actually happens on a timer, not just on your next edit, so a transient failure
(for example, a non-fast-forward push right after a publish touched the same branch)
resolves itself without you noticing.

## Publish: a full push, then a merge

Publish deliberately does **not** reuse the incremental logic. It pushes the complete
current tree to `wip` first — every file, not just what changed — specifically so the
branch about to become live can never be missing something an earlier incremental
checkpoint's hash-tracking might have drifted on. Only after that full push succeeds
does it ask GitHub to merge `wip` into `main`.

This means `main` only ever moves when you explicitly publish. You can checkpoint as
often as you like — abandon an idea, try something risky, come back the next day — and
none of it reaches players until you choose to promote it.

## What this buys you

- **A safety net that isn't a release channel.** Work is never sitting only in the
  browser, but it's also never accidentally live.
- **A cheap, frequent save.** Checkpoints only upload what changed, so they stay fast
  even as a mod's asset set grows.
- **A predictable, reviewable diff on `main`.** Every commit that lands on `main` came
  from an explicit Publish action with a commit message you control, not from every
  keystroke along the way.

## See also

- [The Publish Flow](https://diceytable.com/docs/mods/publishing/publish-flow)
- [Registration & Multiplayer Play](https://diceytable.com/docs/mods/publishing/registration-and-play)
