Sync & Conflict Resolution

Sync is how local checkpoints become available to the rest of the team. Clustta's sync model is explicit, selective, and conflict-aware - your work is never silently overwritten, and you control exactly when changes are pushed and pulled.

The model

Clustta keeps a local .clst project database and gives you control over file and checkpoint transfers. Some collaboration metadata, including statuses, assignments, task settings, and collection sharing, is sent immediately when the server is reachable. Offline changes remain local until sync. See Sync Model for the distinction.

Sync moves data in both directions:

• Up - your new local checkpoints, status changes, assignments, etc. are sent to the studio server.
• Down - new checkpoints and metadata changes from teammates are pulled to your machine.

Each sync is selective:

• You only download the binary chunks for assets that are assigned to you or live in Shared collections.
• Other people's work-in-progress files don't fill your disk.
• The server filters project data according to your access; sync does not grant visibility to restricted work.

Triggering a sync

Three ways:

• Click Sync in the title bar / studio dropdown
• Press Ctrl+Alt+S (Cmd+Alt+S on macOS)
• Toggle Sync after checkpoint in the Create Checkpoint dialog (one-shot)

The status indicator at the top of the app shows current sync state:

• Up to date - local matches server
• Working / busy - sync in progress
• Conflict - needs your attention before sync can finish

Why sync is manual, not automatic

Auto-sync sounds nice in theory. In practice, with creative files, it's a disaster waiting to happen:

• A teammate uploads a half-broken intermediate save → it lands on your disk → your DCC tool reloads it mid-render.
• Two people edit the same scene → the "winner" silently overwrites the loser.
• Slow networks → multi-GB uploads happen in the middle of a Maya save → corruption.

Manual sync means you push when you're at a good stopping point and pull when you're ready to integrate someone else's work. No surprises.

What gets uploaded

When you sync up:

• All new chunks for any new checkpoints since the last sync (delta-only - chunks that already exist on the server are skipped)
• All metadata changes - new assets, status changes, assignments, tags, dependencies, role updates, etc.

The transfer uses content-addressed storage, so chunks shared across files or between teammates are uploaded only once across the entire project.

What gets downloaded

When you sync down:

• All metadata changes from other people
• Chunks for newly-assigned items, including everything pulled in by transitive dependencies
• Updated chunks for items already on your disk where the server has a newer version

You'll then see those items as Outdated until you click them to actually pull the new content into your working file.

Asset states during sync

Assets carry a visual state indicator. After syncing you might see:

State	Meaning	Action
Normal	Up to date	None
Modified	Local edits since last checkpoint	Checkpoint to preserve
Outdated	Server has a newer version	Click to pull
Untracked	New file in working folder, not yet known to Clustta	Click to track
Rebuild	Asset is registered but no local file (new device, freed space)	Click to download

See Collections & Assets for more on managing local files.

The Changes pane lists pending local changes so you can inspect what will be reconciled. It tracks dependency selectors, checkpoint tags, and project tags alongside assets, collections, and templates. Where an undo or restore action is offered, it applies to that item or child change. Some changes cannot be discarded independently; Clustta reports the reason.

Discard all requires confirmation and restores pending project state from the server. Review the listed changes first, particularly new checkpoints and newly created items. Discarding unsynced project changes is a different operation from reverting a working file to a chosen checkpoint.

Local asset and collection renames remain usable while awaiting sync. Remote path changes for fetched items can remain pending until fetch applies them, keeping local files, checkpoints, and reverts aligned. Refresh or fetch the affected item when its local path needs to catch up with the project state.

Project downloads show preparation, receiving, and finishing phases. Cancel requests cancellation while the transfer is active; allow it to finish cancelling before retrying. Cancellation is no longer available during the final setup phase.

If a session expires, sign in again to resume authenticated operations. The desktop app preserves the open project's context during reauthentication, so an expired session does not require closing your local project.

Conflicts

A conflict happens when two collaborators independently created something the server can't merge automatically. Two cases:

1. Same name, same parent collection for two collections.
2. Same name, same parent collection, same extension for two assets.

When sync detects a conflict, it pauses and surfaces a conflict resolution dialog. You get two options per conflict:

Rename (keep mine local, theirs becomes canonical)

• Your local item is renamed (you'll be prompted for the new name).
• The server's version takes the original name.
• Both items now exist independently.
• Your local checkpoints are preserved on the renamed item.

Pick this when both items are legitimately separate things and you want to keep both.

Merge (combine local with server's existing one)

• The two items are reconciled into one.
• Your local checkpoints are stacked on top of the server's checkpoints as new versions.
• No work is lost. Every checkpoint from both sides remains accessible.

Pick this when you and your teammate were working on the same conceptual asset and just both happened to name it the same.

Conflict prevention

Most conflicts are eliminated by the single-assignee soft lock - only the assignee can checkpoint, so the most common case (two people editing the same file) can't happen. Conflicts mostly arise from:

• Two people independently creating a new asset with the same name in the same collection
• Schema-level overlaps (same collection in same parent)

Both are easy to resolve, and Clustta never auto-decides for you.

Tips for healthy sync

• Sync after meaningful work, not after every checkpoint. Local is fine for in-progress.
• Pull before starting on a task you know teammates are also touching.
• Communicate naming for new assets in shared spaces - eliminates rename conflicts.
• Use Shared collections for shared resources so everyone sees them without explicit assignment.
• Selective sync keeps disks small - let the system download only what you actively need.

Quick reference

Action	Shortcut
Sync project	Ctrl+Alt+S (Cmd+Alt+S on macOS)
Pull updates only	Click Sync (will both push and pull)
Resolve conflicts	Modal appears automatically when conflicts detected
See sync state	Title bar status indicator