# Sync > Mirror a project folder between the box and your machine, both directions and .git included, with edits landing on the other side in under a second. URL: https://prized.dev/docs/sync ## The model [#the-model] | Side | Path | | ------------ | ---------------------------- | | box | `~/code/` | | your machine | `~/Prized/` by default | `prized sync add ` creates the pair; `--local` syncs a folder of your own in place, and `local_root` under `[sync]` in the config moves the default parent. The real local copy keeps whole-repo tools fast; to browse the box without copying, use [mount](https://prized.dev/docs/mount). ## How fast [#how-fast] Under a second, except the first edit in a folder nothing has touched for a while, which can take up to 10 seconds to leave the box; `watch_polling_interval` in the project's `[[sync.project]]` entry lowers that, at the cost of a full scan per interval. ## Add a project [#add-a-project] **Nothing exists yet.** `--create` makes `~/code/myproject` on the box: ```bash prized sync add myproject --create ``` **The code is on the box.** The first sync copies `~/code/myproject` down to `~/Prized/myproject` (`C:\Users\you\Prized\myproject` on Windows). For a folder outside `~/code`, pass its path (`prized sync add ~/work/api` names it `api`); `--name` picks the name yourself: ```bash prized sync add myproject ``` **The code is on your machine.** Run setup in the folder, or point it there. Auto mode takes a folder holding a `.git` directory or a manifest (`package.json`, `go.mod`, `pyproject.toml`, and the like) without asking, and asks about any other, so your home folder never syncs by accident. A manual run also asks whether to sync in place (the default) or copy once; 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 local side; setup asks first, since the box 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, and a populated destination is never overwritten. | A checkout others or several agents edit, or a one-time import. | | `--copy` | Copies (never moves) the folder into `~/Prized/myproject` and syncs the copy; a hard link inside is refused. | Leaving the original untouched. | | `--clone` | Clones the folder's `origin` to `~/code/myproject` on the box at your current branch; no sync, 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`. | Rule for every add | What happens | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Both sides have content | `add` refuses until you pass `--merge` (`prized setup --merge` passes it through), which accepts the conflict rule below; the local folder is first copied to `~/Prized/.prized/backups/`. | | No nesting | A folder cannot be added inside, around, or on top of another synced folder, on either side. | | 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); `prized sync add` by hand syncs them unless you pass `--ignore .env` ([Bring your environment](https://prized.dev/docs/environment#env-files)). | | Files over 256 MB | 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 but keeps the project, shown as `error` in `prized sync ls` while the daemon retries; `prized sync rm myproject` drops it. Moving the whole folder, `.git` included, can take a couple of minutes: watch the transfer rate on setup's progress line before assuming it is stuck, trim 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 larger than your free disk never finishes its first sync. When free space on any volume sync writes to drops below 2 GB, Prized pauses every synced project and `prized sync ls` says so: ```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 folders that should not travel (render output, datasets, media), then `prized sync resume --all`. While a volume is below the line, a resume is refused and a newly added project starts paused; `prized sync add` onto a volume that is itself below it is refused. The threshold is `min_free_disk_gb` under `[sync]` in the config (`0` turns the guard off), applied 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, since agents there write fast; in a folder synced in place, your own checkout is the side that yields. `--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 history, diffs, and blame in `~/Prized` is always safe; committing from your machine is safe only while the box side is quiet, or the local commit can be lost. ## Offline [#offline] Agents, builds, and servers keep running while your laptop is offline; sync and mirrored ports catch up on reconnect. Before editing offline where an agent also writes, pause the project, or the box's versions win on reconnect. Behind a proxy, sync uses your Mac's system proxy, or your shell's `HTTPS_PROXY` once you run `prized setup` there ([Networks that block the tunnel](https://prized.dev/docs/troubleshooting#networks-that-block-the-tunnel)). ## Everyday commands [#everyday-commands] | Command | What it does | | ------------------------------ | -------------------------------------------------------------------------------------------------- | | `prized sync` | List projects with state and conflicts (same as `prized sync ls`); says so when nothing is synced. | | `prized sync flush myproject` | Force a full sync cycle and wait for it, for example 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 halted because its root folder was deleted refuses to resume, which would propagate the mass delete; use `repair`. ## Remove a project [#remove-a-project] ```bash prized sync rm myproject ``` This stops syncing and leaves the files on both sides. Two flags also move files aside (never `rm -rf`), naming 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`; refused while anything else syncs that folder or one inside it. > Box paths that spell one folder differently, such as `~/code/app` and `/home/ubuntu/code/app`, count as the same folder. ## Several boxes [#several-boxes] Aim sync commands at a box connected with `prized setup --box mango` by adding `--box mango` (or `PRIZED_BOX=mango`); two boxes cannot sync a project under one name, so the second `prized sync add` asks for `--name` ([Boxes](https://prized.dev/docs/boxes#several-boxes)). ## Under the hood [#under-the-hood] Sync runs on Mutagen: Prized uses its own pinned copy, never one on your PATH, and `prized doctor` fetches it if it is missing.