Redesign Zed Gist sync workflow
This commit is contained in:
+142
-175
@@ -1,255 +1,222 @@
|
||||
# Zed 设置同步使用手册
|
||||
# Zed 设置同步手册
|
||||
|
||||
本方案使用 GitHub Gist 中的单个 `zed-settings-sync.json` 同步 Zed 设置。JSON 顶层直接保存各配置文件的路径和完整内容；SHA-256 只在运行时计算，不写入同步文件。
|
||||
本方案把 Zed 的设置、键位、Tasks、文件排除规则、代码片段和主题整理为一个扁平的 `zed-settings-sync.json`，通过 GitHub Gist 在机器间同步。同步文件内部不保存哈希、Gist ID、账号或 token。
|
||||
|
||||
## 1. 同步内容
|
||||
## 准备工作
|
||||
|
||||
会同步：
|
||||
本地安装需要：
|
||||
|
||||
- `settings.json`：界面、字体、主题、编辑器行为及扩展自动安装清单。
|
||||
- `keymap.json`：自定义键位。
|
||||
- `tasks.json`：文件显隐和设置同步任务。
|
||||
- `scripts/` 中的文件显隐及同步脚本。
|
||||
- 非空的 `snippets/` 和 `themes/` 目录。
|
||||
- Node.js
|
||||
- Windows PowerShell，或 macOS/Linux 的 `curl`
|
||||
|
||||
不会同步：
|
||||
|
||||
- GitHub 登录凭据、API Key 和系统环境变量。
|
||||
- 本机保存的 Gist ID 和上次同步哈希。
|
||||
- Zed 数据库、缓存、聊天记录、项目文件及扩展二进制。
|
||||
|
||||
扩展 ID 位于 `settings.json` 的 `auto_install_extensions` 中。导入后由 Zed 在目标平台重新安装扩展。
|
||||
|
||||
## 2. 准备 Gist
|
||||
|
||||
不需要预先创建 Gist：第一次执行 Push 时，如果本机尚未配置 Gist，系统会询问是否自动创建新的 Secret Gist。
|
||||
|
||||
已有 Gist 时，也可以登录 GitHub、打开 <https://gist.github.com/>，复制完整 Gist URL 或末尾的 Gist ID，再通过 `Configure GitHub Gist...` 关联。
|
||||
|
||||
Gist ID 不是访问令牌。身份认证由 GitHub CLI `gh` 管理。
|
||||
|
||||
Secret Gist 只是不出现在公开搜索中，获得链接的人仍然可以读取其内容。同步 JSON 不包含 API Key，但仍应妥善保管 Gist URL。
|
||||
|
||||
## 3. 主机器首次上传
|
||||
|
||||
### 3.1 安装和认证 GitHub CLI
|
||||
|
||||
当前 Windows 机器已经安装 `gh`。其他机器可以使用系统包管理器安装：
|
||||
启用 GitHub Gist 同步还需要 GitHub CLI `gh`：
|
||||
|
||||
```powershell
|
||||
# Windows
|
||||
winget install GitHub.cli
|
||||
```
|
||||
|
||||
macOS：
|
||||
|
||||
```sh
|
||||
# macOS
|
||||
brew install gh
|
||||
```
|
||||
|
||||
安装后，在 Zed 中按 `Mod+R` 打开 Task Picker，运行：
|
||||
Linux 安装方式见 <https://github.com/cli/cli/blob/trunk/docs/install_linux.md>。
|
||||
|
||||
```text
|
||||
Zed Settings: Authenticate GitHub...
|
||||
```
|
||||
无需提前创建 Gist，也无需手工生成 Personal Access Token。设置向导会调用 GitHub CLI 的浏览器登录流程，并请求 Gist 权限。
|
||||
|
||||
也可以在终端执行：
|
||||
## 第一台机器
|
||||
|
||||
```sh
|
||||
gh auth login
|
||||
```
|
||||
|
||||
### 3.2 创建或关联 Gist
|
||||
|
||||
1. 按 `Mod+R`。
|
||||
2. 没有 Gist 时直接运行 `Zed Settings: Push to GitHub Gist`，确认自动创建。
|
||||
3. 已有 Gist 时先运行 `Zed Settings: Configure GitHub Gist...` 并粘贴 URL/ID，再执行 Push。
|
||||
4. 运行 `Zed Settings: Show GitHub Gist Status`，确认状态为 `Synchronized`。
|
||||
|
||||
Push 只会在该 Gist 中创建或更新 `zed-settings-sync.json`，不会删除 Gist 中的其他文件。
|
||||
|
||||
Gist ID 和上次同步哈希保存在本机：
|
||||
|
||||
```text
|
||||
Windows: %APPDATA%\Zed\scripts\settings-sync.json
|
||||
macOS/Linux: ~/.config/zed/scripts/settings-sync.json
|
||||
```
|
||||
|
||||
此文件不参与导入导出，所以其他机器不会覆盖当前机器记录。
|
||||
|
||||
## 4. 新机器首次接入
|
||||
|
||||
第一次接入只需要运行仓库里的独立 bootstrap 脚本。它会询问 Gist URL/ID，直接读取 Gist 单 JSON，再安装全部设置和同步工具；不需要下载或解压便携目录。
|
||||
|
||||
### 4.1 安装前置程序
|
||||
|
||||
新机器需要：
|
||||
|
||||
- Zed 或 ZedG。
|
||||
- Node.js。
|
||||
- GitHub CLI `gh`。
|
||||
|
||||
bootstrap 仓库本身不保存设置或凭据，只需要包含：
|
||||
|
||||
```text
|
||||
bootstrap-from-gist.ps1
|
||||
bootstrap-from-gist.sh
|
||||
```
|
||||
|
||||
因此这个仓库可以公开；真正的设置仍只存放在指定 Gist 中。
|
||||
|
||||
### 4.2 一行安装
|
||||
### 1. 安装配置
|
||||
|
||||
Windows PowerShell：
|
||||
|
||||
```powershell
|
||||
irm https://git.okk.cool/purp1e/zed-sync/raw/branch/master/bootstrap-from-gist.ps1 | iex
|
||||
irm https://git.okk.cool/purp1e/zed-sync/raw/branch/master/bootstrap.ps1 | iex
|
||||
```
|
||||
|
||||
macOS/Linux：
|
||||
macOS / Linux：
|
||||
|
||||
```sh
|
||||
curl -fsSL https://git.okk.cool/purp1e/zed-sync/raw/branch/master/bootstrap-from-gist.sh | sh
|
||||
curl -fsSL https://git.okk.cool/purp1e/zed-sync/raw/branch/master/bootstrap.sh | sh
|
||||
```
|
||||
|
||||
迁移到其他 Gitea 仓库时，Raw URL 的常见形式是：
|
||||
安装器先完成以下工作：
|
||||
|
||||
```powershell
|
||||
irm https://<Gitea域名>/<用户>/<仓库>/raw/branch/main/bootstrap-from-gist.ps1 | iex
|
||||
```
|
||||
1. 从公开 Gitea 仓库下载默认 `zed-settings-sync.json`。
|
||||
2. 把当前 Zed 配置备份到 `backups/bootstrap-<时间>`。
|
||||
3. 安装设置、键位、Tasks 和同步脚本。
|
||||
4. 创建空的机器本地同步状态。
|
||||
|
||||
```sh
|
||||
curl -fsSL https://<Gitea域名>/<用户>/<仓库>/raw/branch/main/bootstrap-from-gist.sh | sh
|
||||
```
|
||||
这四步不访问 GitHub。没有 `gh`、没有登录或没有 Gist 都不会造成安装失败。
|
||||
|
||||
执行过程中脚本会：
|
||||
### 2. 连接 GitHub
|
||||
|
||||
1. 检查 Node.js 和 `gh`。
|
||||
2. 在尚未登录时运行 `gh auth login`。
|
||||
3. 询问 Gist URL 或 ID；留空时自动创建新的 Secret Gist。
|
||||
4. 输入已有 Gist 时从 GitHub API 读取配置；留空时使用本仓库的 `zed-settings-sync.json` 种子配置。
|
||||
5. 验证顶层文件路径，防止写出 Zed 配置目录。
|
||||
6. 备份新机器已有配置。
|
||||
7. 安装设置、键位、Tasks、snippets、themes 和辅助脚本。
|
||||
8. 保存 Gist ID 和远端整文件 SHA-256 作为首次同步基线。
|
||||
安装结束时可以选择立即运行向导。稍后操作时：
|
||||
|
||||
安装完成后重启 Zed，运行 `Zed Settings: Show GitHub Gist Status`，状态应为 `Synchronized`。
|
||||
1. 重启或 Reload Zed。
|
||||
2. 按 `Mod+R` 打开 Task Picker。
|
||||
3. 运行 `Zed Settings: Set Up / Reconfigure Sync...`。
|
||||
4. 如果尚未登录，终端会显示一次性代码并打开 GitHub 浏览器授权页面。
|
||||
|
||||
为了降低执行远程脚本的供应链风险，可以把 URL 中的 `main` 换成审核过的 commit SHA。bootstrap 仓库不应加入访问令牌或其他秘密。
|
||||
脚本按以下顺序选择凭据：
|
||||
|
||||
### 4.3 便携目录备用安装
|
||||
1. 验证当前 `GH_TOKEN` / `GITHUB_TOKEN`，包括 Gist 权限。
|
||||
2. 环境 token 无效时，移除它们后验证 GitHub CLI 凭据存储。
|
||||
3. 都不可用时启动浏览器登录。
|
||||
|
||||
不能访问 Raw URL 时，仍可复制完整 `zed-config-portable` 目录并运行：
|
||||
同步脚本本身不会读取、打印或保存 token。
|
||||
|
||||
```powershell
|
||||
.\install.ps1
|
||||
```
|
||||
### 3. 创建首个 Gist
|
||||
|
||||
```sh
|
||||
sh ./install.sh
|
||||
```
|
||||
登录后向导会搜索当前账号下包含 `zed-settings-sync.json` 的 Gist。第一台机器通常没有结果：
|
||||
|
||||
然后在 Task Picker 中认证 GitHub、配置 Gist 并执行首次 Pull。
|
||||
1. 选择 `N. Create a new Secret Gist from this machine`。
|
||||
2. 向导创建 Secret Gist 并上传当前 Zed 设置。
|
||||
3. Gist ID 和当前 SHA-256 被记录到本机 `scripts/settings-sync.json`。
|
||||
4. 自动同步保持默认关闭，除非明确选择开启。
|
||||
|
||||
## 5. 之后的日常使用
|
||||
Secret Gist 不会出现在公开列表或搜索中，但知道链接的人仍可读取它。
|
||||
|
||||
开始在一台机器工作前：
|
||||
## 新机器
|
||||
|
||||
1. 按 `Mod+R`。
|
||||
2. 运行 `Zed Settings: Show GitHub Gist Status`。
|
||||
3. 如果显示 `Remote changes available`，执行 Pull。
|
||||
1. 安装 Node.js；需要同步时再安装 `gh`。
|
||||
2. 执行与第一台机器相同的一行安装命令。
|
||||
3. 运行 `Set Up / Reconfigure Sync...`。
|
||||
4. 使用同一个 GitHub 账号完成浏览器登录。
|
||||
5. 向导会自动列出已有的 Zed 设置 Gist；通常只有一个，直接选择即可。
|
||||
6. 初始同步方向选择 `P. Pull remote settings onto this machine`。
|
||||
7. Pull 前默认安装产生的本地配置会被再次备份，然后替换为云端设置。
|
||||
8. Reload Zed。
|
||||
|
||||
修改设置、键位、Tasks、排除规则或 snippets 后：
|
||||
只有在使用其他账号、别人共享的 Gist 或自动发现失败时，才需要选择 `M` 并粘贴 Gist URL/ID。
|
||||
|
||||
1. 执行 Push。
|
||||
2. 确认状态变为 `Synchronized`。
|
||||
3. 再到其他机器执行 Pull。
|
||||
## 日常手动同步
|
||||
|
||||
常用快捷键：
|
||||
推荐默认使用手动同步，方向明确：
|
||||
|
||||
| 快捷键 | 操作 |
|
||||
- 修改设置、键位、Tasks、代码片段或主题后，在当前机器运行 `Push Now`。
|
||||
- 切换到另一台机器后运行 `Pull Now`。
|
||||
- 不确定状态时先运行 `Show Sync Status`。
|
||||
|
||||
快捷键：
|
||||
|
||||
| 键位 | 操作 |
|
||||
|---|---|
|
||||
| `Mod+; U` | Push Now |
|
||||
| `Mod+; D` | Pull Now |
|
||||
| `Mod+R` | 打开 Task Picker |
|
||||
| `Mod+; U` | Push 到 Gist |
|
||||
| `Mod+; D` | 从 Gist Pull |
|
||||
| `Mod+; K` | Reload Zed |
|
||||
|
||||
`Mod` 在 Windows/Linux 是 Ctrl，在 macOS 是 Command。
|
||||
Push 发现远端已经变化时会显示本地、远端和同步基线哈希，并在覆盖前确认。Pull 发现本地已经变化时同样确认，并始终先创建备份。
|
||||
|
||||
## 6. 哈希和冲突处理
|
||||
## 自动同步
|
||||
|
||||
系统比较三个 SHA-256：
|
||||
运行 `Zed Settings: Enable Automatic Sync`：
|
||||
|
||||
- 当前机器实时生成的单 JSON 哈希。
|
||||
- Gist 中单 JSON 的哈希。
|
||||
- 当前机器上次成功 Push/Pull 时保存的哈希。
|
||||
1. 验证已经配置 Gist。
|
||||
2. 验证 GitHub CLI 的系统凭据存储，而不是依赖临时环境 token。
|
||||
3. 安装当前用户级的 15 分钟定时任务。
|
||||
4. 把 `auto_sync` 写为 `true`。
|
||||
|
||||
Status 可能显示：
|
||||
关闭时运行 `Disable Automatic Sync`，它会删除对应的系统调度项并保留 Gist 关联和同步基线。
|
||||
|
||||
| 状态 | 含义 | 建议操作 |
|
||||
系统实现：
|
||||
|
||||
- Windows：Task Scheduler，任务名 `ZedSettingsSync`。
|
||||
- macOS：LaunchAgent `cool.okk.zed-settings-sync.plist`。
|
||||
- Linux：systemd user timer；没有 systemd 时使用带 `# zed-settings-sync` 标记的 crontab。
|
||||
|
||||
自动同步只处理方向明确的单边变化：
|
||||
|
||||
| 本地 | 远端 | 基线 | 结果 |
|
||||
|---|---|---|---|
|
||||
| 相同 | 相同 | 任意 | 无操作 |
|
||||
| 已变 | 等于基线 | 存在 | 自动 Push |
|
||||
| 等于基线 | 已变 | 存在 | 备份后自动 Pull |
|
||||
| 已变 | 已变 | 存在 | 冲突，停止 |
|
||||
| 不同 | 不同 | 不存在 | 无基线，停止 |
|
||||
|
||||
冲突、无基线、认证失效和网络错误不会触发覆盖。相同错误只通知一次，详细记录写入：
|
||||
|
||||
```text
|
||||
Windows: %APPDATA%\Zed\logs\settings-sync.log
|
||||
macOS/Linux: ~/.config/zed/logs/settings-sync.log
|
||||
```
|
||||
|
||||
日志超过 1 MB 后保留最多三份历史文件。
|
||||
|
||||
## 冲突恢复
|
||||
|
||||
`Show Sync Status` 可能显示：
|
||||
|
||||
| 状态 | 含义 | 建议 |
|
||||
|---|---|---|
|
||||
| `Synchronized` | 本地和 Gist 一致 | 无需操作 |
|
||||
| `Local changes pending upload` | 只有本机有变化 | Push |
|
||||
| `Remote changes available` | 只有 Gist 有变化 | Pull |
|
||||
| `Conflict` | 本机和 Gist 都有变化 | 先导出本地备份，再决定 Push 或 Pull |
|
||||
| `Not synchronized on this machine` | 这台机器尚无同步基线 | 首次接入通常选择 Pull |
|
||||
| `synchronized` | 本地和远端一致 | 无需操作 |
|
||||
| `local-changed` | 只有本地变化 | Push Now |
|
||||
| `remote-changed` | 只有远端变化 | Pull Now |
|
||||
| `conflict` | 两边都变化 | 先 Export JSON，再决定保留哪一边 |
|
||||
| `no-baseline` | 机器没有可靠同步基线 | 检查内容后手动 Push 或 Pull |
|
||||
| `remote-missing` | Gist 中缺少同步文件 | 重新配置或手动 Push |
|
||||
|
||||
Push 覆盖远端前、Pull 覆盖本地前都会显示哈希并要求确认。Pull 会自动备份本地配置；系统不会尝试逐字段自动合并。
|
||||
发生冲突时不要连续试 Push/Pull。先运行 `Export JSON...` 保存本机单文件；需要保留远端时执行 Pull，需要保留本机时执行 Push。两个方向在覆盖前都会再次确认。
|
||||
|
||||
## 7. 离线 JSON 导入导出
|
||||
## 导入、导出与备份
|
||||
|
||||
不使用 Gist 时，也可以使用完全相同的单 JSON 格式：
|
||||
`Export JSON...` 和 `Import JSON...` 会打开系统文件选择器。导出的 JSON 与 Gist 中的格式完全相同，顶层键直接是文件路径，例如：
|
||||
|
||||
```text
|
||||
Zed Settings: Export JSON...
|
||||
Zed Settings: Import JSON...
|
||||
```json
|
||||
{
|
||||
"settings.json": "...",
|
||||
"keymap.json": "...",
|
||||
"tasks.json": "..."
|
||||
}
|
||||
```
|
||||
|
||||
两个命令都会弹出系统文件选择窗口。直接 Import 不会修改已保存的 Gist ID 和上次同步哈希；导入内容会被视为新的本地变化，可以随后 Push 到 Gist。
|
||||
没有 `files` 外壳，也没有内置哈希。Import 不会覆盖本机保存的 Gist ID、自动同步设置或上次同步哈希，但导入后的内容会被识别为新的本地变化。
|
||||
|
||||
## 8. 修改文件排除规则
|
||||
|
||||
只编辑本机配置中的 `custom` 数组：
|
||||
|
||||
```text
|
||||
Windows: %APPDATA%\Zed\scripts\file-exclusions.json
|
||||
macOS/Linux: ~/.config/zed/scripts/file-exclusions.json
|
||||
```
|
||||
|
||||
修改后按 `Alt+Shift+-` 测试显隐，再 Push 到 Gist。其他机器 Pull 后会取得相同规则。
|
||||
|
||||
## 9. 备份位置
|
||||
|
||||
每次 Import 或 Pull 前的备份位于：
|
||||
Import 和 Pull 的备份目录：
|
||||
|
||||
```text
|
||||
Windows: %APPDATA%\Zed\backups\sync-import-<时间>
|
||||
macOS/Linux: ~/.config/zed/backups/sync-import-<时间>
|
||||
```
|
||||
|
||||
便携安装器产生的备份使用 `portable-install-<时间>` 名称。
|
||||
## 修改文件排除规则
|
||||
|
||||
## 10. 常见问题
|
||||
编辑：
|
||||
|
||||
### Task Picker 中没有 Zed Settings
|
||||
```text
|
||||
Windows: %APPDATA%\Zed\scripts\file-exclusions.json
|
||||
macOS/Linux: ~/.config/zed/scripts/file-exclusions.json
|
||||
```
|
||||
|
||||
重新运行一行 bootstrap 命令，或运行便携目录中的 `install.ps1` / `install.sh`，然后 Reload Zed。
|
||||
- `defaults`：始终排除的 Zed 默认规则。
|
||||
- `custom`：按 `Alt+Shift+-` 切换的自定义规则。
|
||||
|
||||
### 提示找不到 gh
|
||||
修改后先测试显隐，再运行 Push Now。其他机器 Pull 后会取得相同规则。
|
||||
|
||||
安装 GitHub CLI 后完全退出并重启 Zed，使编辑器读取更新后的 PATH。
|
||||
## 故障排查
|
||||
|
||||
### Gist 返回 404
|
||||
### Task 没有反应
|
||||
|
||||
检查 Gist URL/ID、当前 GitHub 账号以及 Gist 是否仍然存在。重新运行 `Configure GitHub Gist...` 可以更换记录。
|
||||
新版 Setup、Status、Push、Pull、启用和禁用自动同步都会打开并保留终端。先查看终端中的完整错误；确认 Zed 已 Reload，且 Task 名称不是旧版的 `Configure GitHub Gist`。
|
||||
|
||||
### Gist 中没有 zed-settings-sync.json
|
||||
### 环境 token 导致认证异常
|
||||
|
||||
先在已经配置好的主机器上执行一次 Push。
|
||||
脚本会先验证环境 token。无效时会自动回退到凭据存储，并在终端说明。若希望清理环境变量，可检查系统、Shell Profile 和 Zed 的 terminal env 设置。
|
||||
|
||||
### Pull 后键位或界面没有立即变化
|
||||
### GitHub 已登录但不能访问 Gist
|
||||
|
||||
执行 `Mod+; K` Reload Zed；如果扩展仍在安装，等待完成后再重启一次。
|
||||
运行 `Set Up / Reconfigure Sync...`。向导会调用 `gh auth refresh --scopes gist` 补充权限。
|
||||
|
||||
### 换了另一个 Gist
|
||||
### 自动同步一直认证失败
|
||||
|
||||
运行 `Configure GitHub Gist...` 并输入新 ID。系统会保留新 ID，同时清空旧 Gist 对应的上次同步哈希，下一次 Push/Pull 会重新确认覆盖方向。
|
||||
后台任务不能依赖只存在于某个终端进程中的 `GH_TOKEN`。重新运行设置向导并完成浏览器登录，让 `gh` 把凭据保存到系统凭据存储，然后重新启用自动同步。
|
||||
|
||||
### Pull 后没有立即生效
|
||||
|
||||
先运行 `Show Sync Status` 确认哈希一致，再执行 `Mod+; K` Reload Zed。某些扩展和 UI 状态仍可能需要完整重启。
|
||||
|
||||
### 更换或删除 Gist
|
||||
|
||||
运行 `Set Up / Reconfigure Sync...` 重新选择、输入或创建 Gist。切换成功后会建立新的同步基线。删除远端 Gist 前建议先 Export JSON。
|
||||
|
||||
Reference in New Issue
Block a user