# Sync > A synced project is one folder pair, ~/code/ on the box mirrored into a folder on your machine. Edits land on the other side in under a second, both directions, .git included. URL: https://prized.dev/docs/sync ## The model [#the-model] | Side | Path | | ------------ | ---------------------------- | | box | `~/code/` | | your machine | `~/Prized/` by default | `prized sync add ` wires the pair and keeps it mirrored both ways. `--local` syncs a folder of your own in place, and `local_root` under `[sync]` in the config moves the default parent for everything. Sync keeps a real local copy, which is what makes tools that scan a whole repo fast. To browse the box without copying anything, use [mount](https://prized.dev/docs/mount). ## How fast [#how-fast] Edits in a folder that changed recently land on the other side in under a second. The first edit in a folder nothing has touched for a while can take up to 10 seconds to leave the box; `watch_polling_interval` under a project's `[[sync.project]]` entry lowers that, at the cost of a full scan per interval. ## Add a project [#add-a-project] Pick the case that matches where the code is today. **Nothing exists yet.** `--create` makes `~/code/myproject` on the box, and the empty pair fills up as you or an agent work: ```bash prized sync add myproject --create ``` **The code is on the box.** The first sync copies `~/code/myproject` down into `~/Prized/myproject` (`C:\Users\you\Prized\myproject` on Windows). Pass a path for a folder outside `~/code` (`prized sync add ~/work/api` derives the name `api`); a name that cannot be a project name is folded into one, and `--name` picks one yourself: ```bash prized sync add myproject ``` **The code is on your machine.** Point setup at the folder, or run it there: setup offers the folder it runs in, and takes it without asking in auto mode when it holds a `.git` directory or a manifest (`package.json`, `go.mod`, `pyproject.toml`, and the like). Any other folder gets one yes or no first, so your home folder or Desktop never syncs by accident. A manual run asks one more: sync it in place (the default) or copy it to the box once with no sync; two more modes are flags: ```bash prized setup ~/src/myproject # asks: sync in place? (n = copy once) prized setup ~/src/myproject --copy-once # copy to ~/code/myproject on the box, no sync prized setup ~/src/myproject --copy # sync a copy under ~/Prized prized setup ~/src/myproject --clone # git clone on the box, no mirror ``` | Mode | What happens | Right for | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | **In place** | Your folder becomes the live local side; setup asks first, because the box now wins conflicts there. | A project one person edits. | | `--copy-once` | One upload to `~/code/myproject`, `.git` included, ignored paths and `.env` files left out; no sync session, and a populated destination is never overwritten. | A checkout others or several agents edit, or a one-time import. | | `--copy` | Copies the folder into `~/Prized/myproject` (never a move) and syncs the copy; the original is out of the loop. A hard link inside the folder is refused. | Leaving the original untouched; retire it once the copy is in use. | | `--clone` | Clones the folder's `origin` to `~/code/myproject` on the box at your current branch; no sync session, work moves by push and pull. | A checkout others edit, worktrees, uncommitted work in flight. | In place by hand is `prized sync add --local ~/src/myproject --create`. A clone is not a sync project, so it never appears in `prized sync ls`. Rules for every add: * **Both sides already have content:** `add` refuses until you pass `--merge` (`prized setup --merge` passes it through), which accepts the conflict rule below; a copy of the local folder is kept under `~/Prized/.prized/backups/` first. * **No nesting:** a folder cannot be added inside, around, or on top of another synced folder, on either side of the pair. * **Ignored by default:** `node_modules`, `.next`, `dist`, `build`, `out`, `target`, `.venv`, `venv`, `__pycache__`, `.turbo`, `coverage`, `*.log`, `.DS_Store`, `._*`, `.tox`, `.nox`, `.mypy_cache`, `.pytest_cache`, `.ruff_cache`, `.ipynb_checkpoints`, `.pnpm-store`, `.parcel-cache`, `.nuxt`, `.svelte-kit`, `.cache`, `.gradle`, `.terraform`. Adjust per project with `--ignore` and `--unignore`. * **`.env` files:** a session `prized setup` creates ignores `.env` and `.env.*` (`.env.example` still syncs); credential files move through setup's secrets question. `prized sync add` by hand syncs them unless you pass `--ignore .env`. See [Bring your environment](https://prized.dev/docs/environment#env-files). * **Files larger than 256 MB are skipped;** `sync add` and `prized sync ls` name every skipped path. If the first sync cannot be set up, `sync add` fails with the reason and keeps the project configured; the daemon retries on its own, `prized sync ls` shows it as `error`, and `prized sync rm myproject` drops it. A first sync can take a couple of minutes, since the whole folder travels, `.git` included; watch the transfer rate on setup's progress line before assuming something is stuck, trim what travels with `--ignore`, or use `--clone` so the box fetches the history from `origin`. ## Low disk on your machine [#low-disk-on-your-machine] A project only finishes its first sync if it fits on your machine: the download is staged in full before it lands in the folder, so a project larger than your free disk fills the disk and never completes. When free space on any volume that sync writes to drops below 2 GB, Prized pauses every synced project and `prized sync ls` says so under the table: ```text title="prized sync ls" NAME STATE LAST CHANGE CONFLICTS LOCAL REMOTE doppel paused - 0 ~/Prized/doppel ~/code/doppel doppel: paused by prizedd — low disk: 1.5 GB free on ~/Prized/doppel, below min_free_disk_gb = 2 ``` Free space, or add `extra_ignores` for the folders that should not travel (render output, datasets, media), then `prized sync resume --all`. Resuming while the disk is still below the line is refused with the same figure, and a project added then starts paused with the same reason. The threshold is `min_free_disk_gb` under `[sync]` in the config; `0` turns the guard off, and both take effect on the next reload. ```toml [[sync.project]] name = 'doppel' extra_ignores = ['artifacts'] ``` ## Conflicts: the box wins [#conflicts-the-box-wins] Sync runs two-way-resolved and the box wins every conflict: agents on the box write at high rate, so a local edit that races one yields. This matters most for a folder synced in place, since the folder you have always edited is now the yielding side. `--prefer mac` flips that per project; `--mode two-way-safe` surfaces conflicts instead of resolving them. ## Git over sync [#git-over-sync] Commit, rebase, and push from a shell on the box. Reading from your machine (history, diffs, blame in `~/Prized`) is always safe; committing from your machine works only while the box side is quiet, since two commits landing at once can lose the local one. ## Offline [#offline] Agents, builds, and servers keep running while your laptop is offline; sync and mirrored ports catch up on reconnect. To edit offline in a project an agent is also writing to, pause the project first, or the box's versions win on reconnect. ## Everyday commands [#everyday-commands] | Command | What it does | | ------------------------------ | ------------------------------------------------------------------------------------------------------------- | | `prized sync` | List projects with their state and conflicts (`prized sync ls` is the same). With nothing synced, it says so. | | `prized sync flush myproject` | Force a full sync cycle and wait for it. Useful before switching machines. | | `prized sync pause myproject` | Stop syncing until you resume. `--all` works too. | | `prized sync resume myproject` | Resume a paused project. | | `prized sync repair myproject` | Recover a halted session with a safe re-scan. No deletions propagate. | > A session that halted after a folder was deleted at its root refuses to resume, since that would propagate the mass delete. Use `repair`. ## Remove a project [#remove-a-project] ```bash prized sync rm myproject ``` This stops the sync and leaves files on both sides. Two flags go further; both are moves, never `rm -rf`, and both name the exact path in the confirm: * **`--delete-local`** moves the local folder to the Trash after you type `delete-local`; for a project synced in place that is your own checkout. * **`--delete-box`** moves the box folder aside after you type `delete-box`; it is refused when anything else still syncs that folder or one inside it. > Two box paths that spell the same folder differently count as the same folder, `~/code/app` and `/home/ubuntu/code/app` included. ## Several boxes [#several-boxes] Sync commands follow the box you aim them at: the default box, or `--box mango` (or `PRIZED_BOX=mango`) for a box connected with `prized setup --box mango`. Two boxes cannot sync a project under the same name; the second `prized sync add` asks for `--name`. See [Boxes](https://prized.dev/docs/boxes#several-boxes). ## Under the hood [#under-the-hood] Sync runs on Mutagen. Prized installs and manages its own pinned copy and ignores any on your PATH; `prized doctor` fetches it if it is missing.