Cloud collaboration with Drafts

Top menu → Cloud save (desktop app, folder-based project).

YarnDraft uses Git in the background, but writers work with Drafts: each person gets a safe workspace that can be saved to the cloud and reviewed before it reaches the shared Main version.

Connect a project

Choose the path that matches your project.

Standalone story project: Publish

Use Publish when the YarnDraft project is a normal folder that is not already inside a Git repository.

1. Select Publish.
2. Create a completely empty repository using New repository on GitHub or New project on GitLab.
3. Do not add a README, .gitignore, license, or any other starter file.
4. Paste the repository URL into YarnDraft and select Upload and publish.

YarnDraft rejects a non-empty repository with a friendly message. It does not pull unrelated history, overwrite it, or force-push your project.

Project inside an existing game repository

Studios can keep YarnDraft inside an existing game repository, including a large Unreal project:

1. Clone the game repository with your usual Git client, such as GitHub Desktop, Sourcetree, or the command line.
2. Create or open the YarnDraft project in a folder inside that clone, for example Content/YarnDraft.
3. YarnDraft detects the surrounding repository and hides Publish. The existing remote and team workflow remain in charge.

Only files inside the YarnDraft project folder are included when YarnDraft saves. It never runs a repository-wide git add . and does not include modified game code, Blueprints, or engine settings in a Draft.

Daily work

1. New Draft — optionally enter a human-friendly name for today's work. If you leave it empty, YarnDraft creates a local timestamped name that you can rename later; renaming never changes the Git branch.
2. Save to Cloud — save and upload only this YarnDraft project's files to its Draft.
3. Update from base — include the latest Main changes. YarnDraft automatically combines safe story changes and asks only about meaningful conflicts.
4. Submit for Review — open the GitHub or GitLab review page. Complete the pull/merge request there, then confirm the submission in YarnDraft.
5. Close Draft — after review, verify that the work reached Main and return to the shared version.

Review and approval happen on GitHub or GitLab; YarnDraft opens the correct comparison page but does not approve its own work.

Before Cloud Backup creates its first commit for a project, YarnDraft asks for a Git author name and email address if the project does not already have one. It can prefill values from your effective Git configuration, but saves the confirmed author only in that project's local Git configuration.

Remote updates

By default, YarnDraft checks a connected repository for remote changes when you open a project, return to the app, and at a 10-minute interval. The check only fetches status: it never pulls, merges, or changes project files automatically. If remote work is newer, a dismissible banner opens Cloud save, where the existing manual Fetch, Update from base, and merge controls remain available.

You can disable automatic remote checks or set their interval from Settings → General. Manual Fetch remains available when automatic checks are off.

Under Review

After creating the pull/merge request on the provider website, select I submitted the review in YarnDraft. This marks the Draft as Under Review on this computer. It is a local workflow state: YarnDraft does not query GitHub or GitLab to confirm that the review exists or track its approval status.

You can continue using Save to Cloud and Update from base while the Draft is under review. Close Draft performs the real safety check: it fetches Main and verifies that the Draft content was included before removing anything.

Human-readable change details

The technical details keep each stable Git path and ID for debugging, and show the corresponding YarnDraft name beside it when available. For deleted Flows, entities, templates, variable sets, and assets, YarnDraft reads the last committed project version so the old name can still be displayed.

Safety in a shared game repository

• Modified, added, deleted, or staged files outside the YarnDraft folder block Draft operations. Commit or stash them in your usual Git client first.
• Untracked files outside YarnDraft are usually ignored. If one would be overwritten by a Draft switch, YarnDraft stops and asks for help instead.
• YarnDraft commits only its own project folder. It never uses force-push to overwrite cloud content or history. Closing a proven Draft is different: its matching cloud branch is deleted with an exact --force-with-lease, so a newer remote change is preserved.
• Conflicts in game code or other non-YarnDraft files must be resolved or aborted in the team's usual Git client.

Story-aware conflict resolution

YarnDraft compares story content by stable IDs instead of showing raw JSON conflict markers.

• If one person deletes a card while another creates a connection to it, choose Restore the card or Remove the connection.
• If an entity is deleted while a card starts referring to it, YarnDraft shows its name from the common starting version. Choose to restore it, replace the reference, or remove the reference.
• Purely visual changes such as card position do not interrupt the review; Main wins those conflicts automatically.
• Before saving the result, YarnDraft validates graph connections, entity references, assets, variables, folders, and hierarchy cycles so the merged project cannot keep broken references.

Interrupted updates

If YarnDraft closes during an update, reopen the project and choose Continue update or Undo update. Editing stays locked until that recovery choice is complete, so the saved Draft is not overwritten.

If another Git application started the unfinished merge, YarnDraft identifies it as an external update and leaves it untouched. Finish or abort it in that Git application, then refresh YarnDraft.

Closing a Draft safely

Selecting Close Draft first fetches the latest Main and checks whether the Draft was included. YarnDraft can prove this from normal merge ancestry, an exact YarnDraft content match after a squash or rebase, or a semantic content match when Main also contains unrelated later work. This check alone does not delete an unmerged Draft.

If inclusion cannot be proven, YarnDraft summarizes which YarnDraft areas may still be missing and asks what to do:

Permanent discard

Delete and discard Draft explicitly authorizes permanent removal of changes that are not present in Main. Use it only after confirming that the review was rejected or intentionally closed without merging. Choose Cancel to keep the Draft if you are unsure.

Only a successful inclusion proof or that explicit discard confirmation allows closing to continue. Before deleting anything, YarnDraft also checks the cloud Draft against the version used for the close decision. If the cloud Draft has newer or different work (REMOTE_DRAFT_CHANGED), closing stops and neither the local nor the cloud Draft is deleted.

After that precheck, YarnDraft returns to Main and removes the local Draft. It deletes the matching cloud branch with an exact --force-with-lease; if that later lease, deletion, or cleanup step fails, the local Draft remains safely closed and the cloud branch remains for a lead programmer.

Requirements

• Project saved to a folder (not memory-only)
• YarnDraft desktop app
• Git installed on the system
• Network access and permission to push to the remote repository

Sync folder vs. Git

Dropbox/OneDrive folder sync is not a substitute for Git. Avoid editing the same project on two computers through a sync folder while YarnDraft is open.