Skip to content

Commit fee40c5

Browse files
warmenhovenwarmenhoven
committed
Update docs for cloud sync
1 parent 56a1676 commit fee40c5

File tree

2 files changed

+189
-45
lines changed

2 files changed

+189
-45
lines changed

‎docs/guides/retroarch-cloud-sync.md‎

Lines changed: 188 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,69 +1,213 @@
1-
# What is it?
1+
# RetroArch Cloud Sync
22

3-
RetroArch Cloud Sync enables a seamless synchronization of the most important system configuration and save data to a dedicated private webdav server, from where these data can be synchronized across your devices.
3+
Cloud Sync enables seamless synchronization of configuration and save data to a cloud server, allowing you to keep multiple devices in sync.
44

5-
RetroArch Cloud Sync currently syncs all data from the following directories:
5+
## Supported Backends
66

7-
/"YourUser"/Documents/RetroArch/saves - original system saves
8-
/"YourUser"/Documents/RetroArch/states - RetroArch save states
9-
/"YourUser"/Library/Application Support/RetroArch/config - all core-specific configurations, core options and shader configurations, MAME/FBNeo hiscores, but not the global retroarch.cfg
7+
There are three cloud sync backends available:
108

11-
"YourUser" refers to your $HOME user in MacOS
9+
| Backend | Platforms | Notes |
10+
|---------|-----------|-------|
11+
| **WebDAV** | All | Requires server URL, username, and password |
12+
| **iCloud** | macOS, iOS, tvOS | Uses CloudKit (Apple's database service) |
13+
| **iCloud Drive** | macOS, iOS | Uses iCloud Drive file storage |
1214

13-
## How to configure it
15+
### WebDAV
1416

15-
As with any sync solution, it is recommended to start with one device and ensure a proper functioning. Only then further devices should be added.
17+
WebDAV is a standard protocol supported by many cloud providers and self-hosted solutions. You'll need:
1618

17-
### Initial configuration with first device
19+
- A WebDAV server URL (e.g., `https://webdav.example.com/RetroArch/`)
20+
- Username and password
1821

19-
In order to start with Cloud sync, you need an own webdav account that is accessible by MacOS via the Menu/Connect to Server -> https://webdav.xxxxxx.xxx/.
22+
### iCloud vs iCloud Drive
2023

21-
!!! Tip
22-
It is obviously the best way to start with your leading RetroArch system, as this will bring the most important data into the webdav account first. In this account, create an own folder called RetroArch.
24+
Both use your Apple iCloud account but work differently:
2325

24-
Within RetroArch, go to Settings/Saving/Cloud Sync
25-
Enable Cloud Sync -> ON
26-
Destructive Cloud Sync -> OFF (keeps a backup in a dedicated subfolder called "deleted", and the file names get a time stamp of deletion)
27-
Cloud Sync Backend -> webdav
28-
Cloud Storage URL -> https://webdav.xxxxxx.xxx/RetroArch/ (here is the RetroArch subfolder that you created before)
29-
Username -> your webdav user
30-
Password -> your webdav password
26+
- **iCloud** uses CloudKit, Apple's database service. Data is stored in a structured database format.
27+
- **iCloud Drive** stores files directly in iCloud Drive storage, similar to how other apps store documents.
3128

32-
Save this configuration and restart Retroarch. After this restart, the initial sync should start immediately (see progress indicator in the bottom left status line of RetroArch). Depending on your amount of sync data, this can take some time. When this is finished, you could do some testing. For example, launch a game and set a new hiscore, then close the game. Let the sync do its job, then look into the webdav account, and the new hiscore should be there.
29+
!!! note "iCloud Drive files are not visible in Files.app"
30+
Files synced via iCloud Drive are intentionally hidden from the Files app. This is by design—the sync system uses a manifest file to track file hashes, and direct editing of files would corrupt the sync state. Your data is safely stored in iCloud and syncs between devices, but you should only access it through RetroArch.
3331

34-
### Configuration of a second device and further devices
32+
## What Gets Synced
3533

36-
With any additional device, you do the identical steps in RetroArch as with the first device. From now on, these devices should be in sync!
34+
Cloud Sync can synchronize the following directories (each can be enabled/disabled individually):
3735

38-
!!! Tip
39-
Be very careful that these directory save settings are also identical on all sync devices:
40-
- Sort Saves into Folders by Core Name - ON/OFF
41-
- Sort Save States into Folders by Core Name - ON/OFF
42-
- Sort Saves into Folders by Content Directory - ON/OFF
43-
- Sort Save States into Folders by Content Directory - ON/OFF
44-
If these settings are not matching, the sync is likely to fail, as the devices store its data in different directories.
36+
| Directory | Default | Contents |
37+
|-----------|---------|----------|
38+
| **Save Files & States** | On | Game saves (`.srm`) and save states |
39+
| **Configuration** | On | Core configs, core options, shader presets, MAME/FBNeo hiscores |
40+
| **Thumbnails** | Off | Custom thumbnails (use the thumbnail downloader for standard ones) |
41+
| **System Files** | Off | BIOS files, etc. (can be large; use with caution) |
4542

46-
## Further details of the solution
43+
### Excluded Files
4744

48-
### Sync Status
45+
The following are automatically excluded from sync:
4946

50-
Syncing is displayed in the bottom left status line of RetroArch.
47+
- `retroarch.cfg` (main configuration file)
48+
- Playlist files (`content_*.lpl`)
49+
- `.DS_Store` files (macOS)
5150

52-
As soon as the solution is properly configured, Cloud Sync starts immediately at launching RetroArch. This is apparently important if other devices synced new data to the webdav repository. They are then immediately picked up. As of more recent nightly iOS builds, RetroArch also starts Cloud Sync if it is launched from a Background/Suspended State (important for avoiding sync conflicts).
51+
## Configuration
5352

54-
Another sync is triggered with every closing of a game and returning to the RetroArch menu. Be conscious that RetroArch cannot sync a new game status if RetroArch is closed from within a game by pressing Escape/Escape.
53+
### Initial Setup (First Device)
5554

56-
### .DS_Store files will be ignored in sync
55+
Start with your primary RetroArch device to establish the initial cloud state.
5756

58-
As of more recent nightly builds, Cloud Sync ignores .DS_Store files during sync. You can monitor this in the logfiles after turning on logging in RetroARch. But it is nevertheless recommended to delete all .DS_Store files from the synced directories.
57+
1. Navigate to **Settings → Saving → Cloud Sync**
58+
2. Configure the following:
5959

60-
For example, you can delete the .DS.Store files from the relevant RetroArch directories from the terminal as follows (easiest way is that you create an .sh file containing these lines and make it executable via chmod 755):
60+
| Setting | Description |
61+
|---------|-------------|
62+
| **Enable Cloud Sync** | Turn on to enable syncing |
63+
| **Destructive Cloud Sync** | When OFF, deleted/overwritten files are backed up locally |
64+
| **Cloud Sync Backend** | Select your backend (webdav, icloud, or icloud_drive) |
65+
| **Sync Saves** | Sync save files and save states |
66+
| **Sync Configs** | Sync configuration files |
67+
| **Sync Thumbnails** | Sync thumbnail images |
68+
| **Sync System** | Sync system/BIOS files |
6169

62-
cd /"YourUser"/Documents/RetroArch
63-
find . -name '.DS_Store' -type f -delete
64-
cd /"YourUser"/Library/Application\ Support/RetroArch
65-
find . -name '.DS_Store' -type f -delete
70+
For WebDAV, also configure:
6671

67-
### Troubleshooting
72+
| Setting | Description |
73+
|---------|-------------|
74+
| **Cloud Storage URL** | Your WebDAV server URL (include trailing slash) |
75+
| **Username** | WebDAV username |
76+
| **Password** | WebDAV password |
6877

69-
If the Cloud Sync returns an error, turn logging on and set the logging level to debug, log into a file. Cloud Sync logs reliably into the logfile, so the errors can be read easily. Not all conflicts that RetroArch Cloud Sync returns are critical (e.g. cache conflicts that can be easily resolved by deleting the conflicting local cache file according to the logfile). Other conflicts may even be desired, e.g. if core configurations shall differ between the MacOS core and the iOS core.
78+
3. Save the configuration and restart RetroArch
79+
4. The initial sync will begin automatically (watch the status line at the bottom)
80+
81+
### Adding Additional Devices
82+
83+
Configure each additional device with identical settings. Pay special attention to these directory settings—they must match across all devices:
84+
85+
- Sort Saves into Folders by Core Name
86+
- Sort Save States into Folders by Core Name
87+
- Sort Saves into Folders by Content Directory
88+
- Sort Save States into Folders by Content Directory
89+
90+
!!! warning
91+
If these settings don't match, devices will store files in different locations and sync will fail to merge them correctly.
92+
93+
## How Cloud Sync Works
94+
95+
Cloud Sync uses a three-way merge algorithm with two manifest files:
96+
97+
1. **Server Manifest** - Tracks what's stored in the cloud
98+
2. **Local Manifest** - Tracks what was last synced from this device
99+
100+
When sync runs, RetroArch compares:
101+
102+
- Current local files
103+
- Local manifest (what we last synced)
104+
- Server manifest (what the cloud has)
105+
106+
This allows the system to detect:
107+
108+
- New local files → upload to cloud
109+
- New server files → download to device
110+
- Changed files → determine which version is newer
111+
- Deleted files → propagate deletion (or backup if non-destructive)
112+
- Conflicts → when both local and server changed the same file
113+
114+
### Sync Mode
115+
116+
The **Sync Mode** setting controls when synchronization occurs:
117+
118+
| Mode | Behavior |
119+
|------|----------|
120+
| **Automatic** (default) | Syncs on RetroArch startup and when cores are unloaded (returning to menu) |
121+
| **Manual** | Only syncs when you explicitly trigger it via **Sync Now** |
122+
123+
In **Automatic** mode, sync also runs when RetroArch resumes from the background on iOS.
124+
125+
Use **Manual** mode if you want full control over when sync happens, or if you're on a metered connection and want to minimize data usage.
126+
127+
### Sync Now
128+
129+
The **Sync Now** option (in Settings → Saving → Cloud Sync) manually triggers a sync. This works in both Automatic and Manual modes, allowing you to force a sync at any time.
130+
131+
!!! tip
132+
Always close the running content (Close Content) and return to RetroArch's main menu before quitting RetroArch. This ensures your latest saves are synced. Quitting RetroArch while content is still running may skip the sync.
133+
134+
### Conflict Resolution
135+
136+
A conflict occurs when the same file is modified on multiple devices before they have a chance to sync. Specifically, a conflict is detected when:
137+
138+
- The server version differs from what was last synced, AND
139+
- The local version also differs from what was last synced
140+
141+
Another conflict scenario is when one device deletes a file while another device modifies it.
142+
143+
**Current behavior:** When a conflict is detected, RetroArch does not overwrite either version. The local file remains unchanged, the server file remains unchanged, and the conflict is logged. The file is temporarily excluded from sync until manually resolved.
144+
145+
**Identifying conflicts:**
146+
147+
- The status line will show "Cloud Sync finished with conflicts"
148+
- The log file will contain entries like: `[CloudSync] Conflicting change of saves/game.srm`
149+
150+
**Resolving conflicts manually:**
151+
152+
1. Enable debug logging and check the log to identify which files are conflicting
153+
2. Decide which version you want to keep (local or server)
154+
3. To keep the **server** version: delete or rename the local file, then let sync run again to download the server version
155+
4. To keep the **local** version: edit the local manifest file (`manifest.local` in your downloads/core assets directory) and update the conflicting file's hash to match the server's hash. On the next sync, RetroArch will see the local file as changed and upload it
156+
157+
!!! tip
158+
To avoid conflicts, try not to use RetroArch on multiple devices simultaneously. Always let sync complete on one device before starting a session on another.
159+
160+
### Non-Destructive Mode
161+
162+
When **Destructive Cloud Sync** is OFF, files that would be deleted or overwritten are backed up to:
163+
164+
```
165+
[core_assets_directory]/cloud_backups/[path]-YYMMDD-HHMMSS
166+
```
167+
168+
This allows recovery if sync makes unwanted changes.
169+
170+
## Sync Status
171+
172+
Sync progress is displayed in the bottom-left status line. Messages include:
173+
174+
- "Cloud Sync in progress" - Sync is running
175+
- "Cloud Sync finished" - Completed successfully
176+
- "Cloud Sync finished with conflicts" - Completed but conflicts were detected
177+
- "Cloud Sync finished with failures" - Some operations failed
178+
- "Cloud Sync failed" - Could not connect to backend
179+
180+
## Troubleshooting
181+
182+
### Enable Logging
183+
184+
1. Go to **Settings → Logging**
185+
2. Enable **Log to File**
186+
3. Set **Logging Level** to **Debug**
187+
188+
Cloud Sync logs detailed information prefixed with `[CloudSync]`.
189+
190+
### Common Issues
191+
192+
**Sync not starting**
193+
194+
- Verify Cloud Sync is enabled
195+
- Check network connectivity
196+
- For WebDAV: verify URL, username, and password
197+
- For iCloud: ensure you're signed into iCloud on the device
198+
199+
**Files not syncing between devices**
200+
201+
- Ensure directory organization settings match on all devices
202+
- Check that the same sync options (saves, configs, etc.) are enabled
203+
- Wait for sync to complete on one device before starting another
204+
205+
**Conflicts appearing**
206+
207+
- Avoid using multiple devices simultaneously
208+
- Always let sync complete before closing RetroArch
209+
- Check logs to identify which files are conflicting
210+
211+
**iCloud Drive: "Can't see files in Files.app"**
212+
213+
This is intentional. Files are stored in a private app container to protect sync integrity. Your data is syncing correctly even though it's not visible in Files.app.

‎mkdocs.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ nav:
8181
- 'Video Recording and Streaming': 'guides/recording-and-streaming.md'
8282
- 'Troubleshooting': 'guides/troubleshooting-retroarch.md'
8383
- 'Generating Logs': 'guides/generating-retroarch-logs.md'
84-
- 'RetroArch Cloud Sync (Apple Devices)': 'guides/retroarch-cloud-sync.md'
84+
- 'RetroArch Cloud Sync': 'guides/retroarch-cloud-sync.md'
8585
- 'Databases & Validation': 'guides/databases.md'
8686
- 'Appearance & Customization':
8787
- 'Interface Styles':

0 commit comments

Comments
 (0)