From 7f6c4bc81473f3c4186108135d45b2ff4511b3dc Mon Sep 17 00:00:00 2001
From: slaguru666 <111923774+slaguru666@users.noreply.github.com>
Date: Thu, 18 Jun 2026 21:05:51 +0100
Subject: [PATCH] docs: add cross-machine sync guide for -DataRoot/-ConfigRoot

---
 README.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/README.md b/README.md
index 26f975b..f507811 100644
--- a/README.md
+++ b/README.md
@@ -78,6 +78,35 @@ pwsh -File .\install.ps1 -DataRoot C:\tmp\data -ConfigRoot C:\tmp\config -DryRun
 - `-DataRoot`   — defaults to `%APPDATA%\warp\Warp\data` (tab_configs, themes, keybindings.yaml)
 - `-ConfigRoot` — defaults to `%LOCALAPPDATA%\warp\Warp\config` (settings.toml)
 
+### Syncing across machines
+
+The goal is the same on every machine: clone this repo once, then symlink its
+files into wherever that machine's Warp reads its config. On most machines the
+defaults are correct, so you don't pass any roots:
+
+```powershell
+git clone https://github.com/slaguru666/warp-dotfiles.git $env:USERPROFILE\warp-dotfiles
+pwsh -File $env:USERPROFILE\warp-dotfiles\install.ps1
+```
+
+Use `-DataRoot` / `-ConfigRoot` only when a machine stores Warp's config
+somewhere non-standard (e.g. a portable install, a custom `%APPDATA%`, or a
+redirected profile). Point them at that machine's Warp `data` and `config`
+folders:
+
+```powershell
+pwsh -File .\install.ps1 `
+  -DataRoot   D:\PortableWarp\warp\Warp\data `
+  -ConfigRoot D:\PortableWarp\warp\Warp\config
+```
+
+Tip: add `-DryRun` first to confirm the resolved roots before linking. Once
+linked, every machine shares the same tracked files — edit on one, `git push`,
+then `git pull` on the others. Because Warp also runs **Settings Sync** in the
+cloud, prefer keeping device-specific values (startup shell, preferred editor)
+out of the synced `settings.toml`, or drop that entry from `$Entries` as noted
+above.
+
 ## Updating
 
 Because the targets are symlinks back into this repo, edits made in Warp land