How sync works
Commits, the local and cloud heads, and how push and pull keep them in step.
Zeon sync is a small version-control system with one branch, main.
Commits
A commit is a snapshot of the whole project: every file's content, stored by its hash, plus a message and a parent commit. There is no staging area: zeon commit snapshots the working tree as it is now (or only the paths you name, keeping everything else as it was in the last commit). A commit you make is local until you push it.
The cloud records the author and time of each commit when you push; zeon log shows them.
Two heads
Your working tree keeps two pointers in .zeon/:
| Pointer | Meaning | zeon status shows it as |
|---|---|---|
| HEAD | Your latest local commit. | head: |
| Remote head | The cloud commit you last pushed or pulled. | remote head: |
When they are equal and the working tree matches HEAD, you are in step with the cloud as you last saw it.
Push
zeon push uploads the commits the cloud does not have, then moves the cloud's main to your HEAD. It does that only if the cloud is still at your remote head. If someone (or the web app) pushed in the meantime, the push is refused:
the cloud has changed since your last sync — run `zeon sync` to merge your work with the cloud and push.
Nothing is overwritten. Run zeon sync to merge and push.
Pull
zeon pull downloads the cloud's latest commit and merges it into your working tree:
- If you changed nothing, it fast-forwards to the cloud.
- If both sides changed different files, or different lines of a text file, it merges them and records a merge commit; then
zeon push. - If both sides changed the same lines, it writes conflict markers into the file. See Conflicts and a diverged project.
- If both sides changed a binary file, it keeps the cloud's version and saves yours under
.zeon/backups/<path>.
zeon pull refuses to run while you have uncommitted changes (commit first, or --force to merge into them).
Sync
zeon sync is commit, pull and push in one step, and the command to use day to day. See zeon sync.
After a push: your instance
Your cloud instance runs the copy of the project it loaded, not the cloud's latest. After a successful zeon push or zeon sync, the CLI checks whether your instance has this project loaded; if so, it loads the new version and prints instance refreshed (the loaded world is kept; --world W loads one). It skips this quietly when no instance is bound, the instance does not answer within a few seconds, or it has another project loaded. --no-refresh skips it. A refresh that fails never fails the push.
What is in .zeon/
.zeon/.zeon/ holds the local object store (file contents, trees, commits), the two heads, the project id, merge state, and backups from binary merges. It is never synced. Do not edit it; to start over, clone the project again into a new folder.
The CLI finds the project by walking up from the current directory to the first folder with a .zeon/ directory, so project commands work from any subfolder.
Updated 9 days ago