# Zed 设置同步使用手册

本方案使用 GitHub Gist 中的单个 `zed-settings-sync.json` 同步 Zed 设置。JSON 顶层直接保存各配置文件的路径和完整内容；SHA-256 只在运行时计算，不写入同步文件。

## 1. 同步内容

会同步：

- `settings.json`：界面、字体、主题、编辑器行为及扩展自动安装清单。
- `keymap.json`：自定义键位。
- `tasks.json`：文件显隐和设置同步任务。
- `scripts/` 中的文件显隐及同步脚本。
- 非空的 `snippets/` 和 `themes/` 目录。

不会同步：

- 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`。其他机器可以使用系统包管理器安装：

```powershell
winget install GitHub.cli
```

macOS：

```sh
brew install gh
```

安装后，在 Zed 中按 `Mod+R` 打开 Task Picker，运行：

```text
Zed Settings: Authenticate GitHub...
```

也可以在终端执行：

```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 一行安装

Windows PowerShell：

```powershell
irm https://git.okk.cool/purp1e/zed-sync/raw/branch/master/bootstrap-from-gist.ps1 | iex
```

macOS/Linux：

```sh
curl -fsSL https://git.okk.cool/purp1e/zed-sync/raw/branch/master/bootstrap-from-gist.sh | sh
```

迁移到其他 Gitea 仓库时，Raw URL 的常见形式是：

```powershell
irm https://<Gitea域名>/<用户>/<仓库>/raw/branch/main/bootstrap-from-gist.ps1 | iex
```

```sh
curl -fsSL https://<Gitea域名>/<用户>/<仓库>/raw/branch/main/bootstrap-from-gist.sh | sh
```

执行过程中脚本会：

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`。

为了降低执行远程脚本的供应链风险，可以把 URL 中的 `main` 换成审核过的 commit SHA。bootstrap 仓库不应加入访问令牌或其他秘密。

### 4.3 便携目录备用安装

不能访问 Raw URL 时，仍可复制完整 `zed-config-portable` 目录并运行：

```powershell
.\install.ps1
```

```sh
sh ./install.sh
```

然后在 Task Picker 中认证 GitHub、配置 Gist 并执行首次 Pull。

## 5. 之后的日常使用

开始在一台机器工作前：

1. 按 `Mod+R`。
2. 运行 `Zed Settings: Show GitHub Gist Status`。
3. 如果显示 `Remote changes available`，执行 Pull。

修改设置、键位、Tasks、排除规则或 snippets 后：

1. 执行 Push。
2. 确认状态变为 `Synchronized`。
3. 再到其他机器执行 Pull。

常用快捷键：

| 快捷键 | 操作 |
|---|---|
| `Mod+R` | 打开 Task Picker |
| `Mod+; U` | Push 到 Gist |
| `Mod+; D` | 从 Gist Pull |
| `Mod+; K` | Reload Zed |

`Mod` 在 Windows/Linux 是 Ctrl，在 macOS 是 Command。

## 6. 哈希和冲突处理

系统比较三个 SHA-256：

- 当前机器实时生成的单 JSON 哈希。
- Gist 中单 JSON 的哈希。
- 当前机器上次成功 Push/Pull 时保存的哈希。

Status 可能显示：

| 状态 | 含义 | 建议操作 |
|---|---|---|
| `Synchronized` | 本地和 Gist 一致 | 无需操作 |
| `Local changes pending upload` | 只有本机有变化 | Push |
| `Remote changes available` | 只有 Gist 有变化 | Pull |
| `Conflict` | 本机和 Gist 都有变化 | 先导出本地备份，再决定 Push 或 Pull |
| `Not synchronized on this machine` | 这台机器尚无同步基线 | 首次接入通常选择 Pull |

Push 覆盖远端前、Pull 覆盖本地前都会显示哈希并要求确认。Pull 会自动备份本地配置；系统不会尝试逐字段自动合并。

## 7. 离线 JSON 导入导出

不使用 Gist 时，也可以使用完全相同的单 JSON 格式：

```text
Zed Settings: Export JSON...
Zed Settings: Import JSON...
```

两个命令都会弹出系统文件选择窗口。直接 Import 不会修改已保存的 Gist ID 和上次同步哈希；导入内容会被视为新的本地变化，可以随后 Push 到 Gist。

## 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 前的备份位于：

```text
Windows: %APPDATA%\Zed\backups\sync-import-<时间>
macOS/Linux: ~/.config/zed/backups/sync-import-<时间>
```

便携安装器产生的备份使用 `portable-install-<时间>` 名称。

## 10. 常见问题

### Task Picker 中没有 Zed Settings

重新运行一行 bootstrap 命令，或运行便携目录中的 `install.ps1` / `install.sh`，然后 Reload Zed。

### 提示找不到 gh

安装 GitHub CLI 后完全退出并重启 Zed，使编辑器读取更新后的 PATH。

### Gist 返回 404

检查 Gist URL/ID、当前 GitHub 账号以及 Gist 是否仍然存在。重新运行 `Configure GitHub Gist...` 可以更换记录。

### Gist 中没有 zed-settings-sync.json

先在已经配置好的主机器上执行一次 Push。

### Pull 后键位或界面没有立即变化

执行 `Mod+; K` Reload Zed；如果扩展仍在安装，等待完成后再重启一次。

### 换了另一个 Gist

运行 `Configure GitHub Gist...` 并输入新 ID。系统会保留新 ID，同时清空旧 Gist 对应的上次同步哈希，下一次 Push/Pull 会重新确认覆盖方向。