Skip to content

Commit 8ce3361

Browse files
zerx-labzerx-lab
committed
Add migration guides for settings from OpenWarp and Warp
1 parent 11f53c7 commit 8ce3361

6 files changed

Lines changed: 677 additions & 0 deletions

File tree

‎README.ja.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,13 @@ Zap はオープンでローカルファーストなターミナルで、AI と
2323
- **多言語 UI** —— 英語 / 簡体字中国語 / 日本語をデフォルト同梱、コミュニティで拡張可能。
2424
- **プライバシー優先のデフォルト** —— Cloud Agent / Computer Use / Referral / テレメトリはデフォルトでオフ。
2525

26+
## OpenWarp / Warp からの移行
27+
28+
プロジェクトが Zap に改名される前から使っていた方(当時の名称は **OpenWarp**)、
29+
または上流 **Warp** から乗り換える方は、
30+
[docs/migrate-from-warp.ja.md](docs/migrate-from-warp.ja.md) を参照して設定を
31+
引き継いでください。
32+
2633
## ロードマップ
2734

2835
[docs/roadmap.ja.md](docs/roadmap.ja.md) を参照してください。

‎README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,13 @@ Zap is an open, local-first terminal with first-class AI and agent support. Plug
2323
- **Localized UI** — English / Simplified Chinese / Japanese out of the box, community-extensible.
2424
- **Privacy defaults** — Cloud Agent / Computer Use / Referral / telemetry off by default.
2525

26+
## Migrating from OpenWarp or Warp
27+
28+
If you used the project before it was renamed to Zap (formerly **OpenWarp**),
29+
or are coming from upstream **Warp**, see
30+
[docs/migrate-from-warp.md](docs/migrate-from-warp.md) to bring your settings
31+
across.
32+
2633
## Roadmap
2734

2835
See [docs/roadmap.md](docs/roadmap.md).

‎README.zh-CN.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,12 @@ Zap 是一个开放、本地优先的终端,带一等公民的 AI 与 Agent 体
2323
- **多语言界面** —— 原生英文 / 简体中文 / 日语,社区可扩展。
2424
- **隐私默认值** —— Cloud Agent / Computer Use / Referral / 遥测默认关闭。
2525

26+
## 从 OpenWarp 或 Warp 迁移过来
27+
28+
如果你在项目改名 Zap 之前就一直在用(那时还叫 **OpenWarp**),
29+
或者你是从上游 **Warp** 切过来的,参见
30+
[docs/migrate-from-warp.zh-CN.md](docs/migrate-from-warp.zh-CN.md) 把设置带过来。
31+
2632
## 后续计划
2733

2834
见 [docs/roadmap.zh-CN.md](docs/roadmap.zh-CN.md)。

‎docs/migrate-from-warp.ja.md‎

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
# Zap への設定の移行
2+
3+
[English](./migrate-from-warp.md) · [简体中文](./migrate-from-warp.zh-CN.md)
4+
5+
このガイドは、**設定系の構成**(カスタムキーバインド・テーマ・ワークフロー・
6+
MCP 設定など)を以前のインストールから Zap へ引き継ぎたい方向けです。
7+
8+
移行元として想定されるのは 2 つあり、**両者では安全性プロファイルが異なる**ため、
9+
本書では別々のセクションで扱います。両方該当する場合は、**まず OpenWarp から
10+
移行してから** Warp の移行を検討してください。
11+
12+
1. **OpenWarp** —— Zap の以前の名称。プロジェクトが Zap に改名される前から
13+
使っていた場合、旧設定は `~/.openwarp/` に残っている可能性が高いです。
14+
2. **上流の [Warp](https://github.com/warpdotdev/warp)** —— Zap が fork して
15+
いるプロジェクト。設定は `~/.warp/` 配下にあります。
16+
17+
本書は コマンド履歴・SQLite データベース・Drive オブジェクト・認証情報の
18+
いずれも **意図的に対象外** としています。これらはマシン依存のストア
19+
(Keychain / DPAPI / libsecret)、または schema が結合したストアに格納されて
20+
いるため、コピーは安全ではありません。
21+
22+
---
23+
24+
## 1. OpenWarp からの移行(既存ユーザーの推奨経路)
25+
26+
### このケースが安全な理由
27+
28+
OpenWarp は改名前の Zap そのものです。改名コミット
29+
(`feat: rename project Warp/OpenWarp → Zap`)は識別子とディスク上のパス名を
30+
変更しただけで、**設定ファイルのフォーマットと schema は一切変わっていません**。
31+
ディスク上の位置の対応は以下の通りです:
32+
33+
| プラットフォーム | OpenWarp 設定ディレクトリ | Zap 設定ディレクトリ |
34+
|---|---|---|
35+
| macOS | `~/.openwarp/` | `~/.zap/` |
36+
| Linux | `~/.openwarp/` | `~/.zap/` |
37+
| Windows | `%USERPROFILE%\.openwarp\` | `%USERPROFILE%\.zap\` |
38+
39+
schema が一致しているため、下記 7 項目をそのままコピーすれば Zap はそのまま
40+
読み込みます。
41+
42+
| ファイル / ディレクトリ | 役割 |
43+
|---|---|
44+
| `settings.toml` | 公開設定(TOML ベースの設定ファイル)。 |
45+
| `keybindings.yaml` | カスタムキーバインド。 |
46+
| `themes/` | カスタムテーマ。 |
47+
| `workflows/` | カスタムワークフロー。 |
48+
| `launch_configs/` | Launch 設定。 |
49+
| `.mcp.json` | MCP サーバー設定。 |
50+
| `skills/` | Agent skills。 |
51+
52+
### 手順
53+
54+
> コピー前に **Zap を終了**してください。プロセスがファイルを掴んでいると
55+
> 失敗します。
56+
57+
**macOS / Linux**
58+
59+
```sh
60+
mkdir -p "$HOME/.zap"
61+
for f in settings.toml keybindings.yaml themes workflows launch_configs skills .mcp.json; do
62+
if [ -e "$HOME/.openwarp/$f" ] && [ ! -e "$HOME/.zap/$f" ]; then
63+
cp -R "$HOME/.openwarp/$f" "$HOME/.zap/$f"
64+
fi
65+
done
66+
```
67+
68+
**Windows(PowerShell)**
69+
70+
```powershell
71+
$src = "$env:USERPROFILE\.openwarp"
72+
$dst = "$env:USERPROFILE\.zap"
73+
New-Item -ItemType Directory -Force -Path $dst | Out-Null
74+
75+
$items = @(
76+
'settings.toml',
77+
'keybindings.yaml',
78+
'themes',
79+
'workflows',
80+
'launch_configs',
81+
'skills',
82+
'.mcp.json'
83+
)
84+
85+
foreach ($name in $items) {
86+
$from = Join-Path $src $name
87+
$to = Join-Path $dst $name
88+
if ((Test-Path $from) -and -not (Test-Path $to)) {
89+
Copy-Item -Path $from -Destination $to -Recurse
90+
}
91+
}
92+
```
93+
94+
`[ ! -e ... ]` / `-not (Test-Path $to)` のガードは、Zap 側で既にカスタマイズ
95+
した内容を上書きしないためのものです。OpenWarp の値で上書きしたい場合は外して
96+
ください。
97+
98+
Zap が問題なく動くことを確認したら、`~/.openwarp`(または Windows 上の同等
99+
ディレクトリ)を削除してディスク領域を回収できます。もう誰も使っていません。
100+
101+
---
102+
103+
## 2. 上流 Warp からの移行
104+
105+
### このケースが別扱いになる理由
106+
107+
上流 Warp は独立した別プロダクトで、独自のディスク上アイデンティティを持ち
108+
ます:
109+
110+
| プラットフォーム | Warp 設定ディレクトリ | Zap 設定ディレクトリ |
111+
|---|---|---|
112+
| macOS | `~/.warp/` | `~/.zap/` |
113+
| Linux | `~/.warp/` | `~/.zap/` |
114+
| Windows | `%USERPROFILE%\.warp\` | `%USERPROFILE%\.zap\` |
115+
116+
Zap はビルド時の channel が `Oss` で、独自の app id(`dev.zap.Zap`)と独自の
117+
設定ディレクトリを持ちます。両者のインストールは互いに相手のファイルを見る
118+
ことができません —— これは Warp のアカウントやクラウド状態を Zap に持ち込ま
119+
ないための仕様でもあります。
120+
121+
下記のテキスト形式ファイルは schema が安定しており、コピーしても安全です。
122+
**それ以外はそうではありません** —— Warp は Zap とは独立に進化しており、
123+
バイナリ / プライベートストアは Warp の認証や bundle 識別子に紐付いている
124+
場合があります。
125+
126+
### コピー対象
127+
128+
セクション 1 と同じ 7 項目です:
129+
130+
| ファイル / ディレクトリ | 役割 |
131+
|---|---|
132+
| `settings.toml` | 公開設定(TOML ベースの設定ファイル)。 |
133+
| `keybindings.yaml` | カスタムキーバインド。 |
134+
| `themes/` | カスタムテーマ。 |
135+
| `workflows/` | カスタムワークフロー。 |
136+
| `launch_configs/` | Launch 設定。 |
137+
| `.mcp.json` | MCP サーバー設定。 |
138+
| `skills/` | Agent skills。 |
139+
140+
### コピー**してはいけない**もの
141+
142+
- **`user_preferences.json`** —— macOS の
143+
`~/Library/Application Support/dev.warp.Warp/`(Linux / Windows ではそれに
144+
相当する state ディレクトリ)にあるプライベートストアで、ユーザー設定・
145+
認証トークン・マシン依存 ID・クラウドキャッシュが混在しています。ファイル
146+
ごとコピーすると ID 情報が漏れたり、Zap の認証状態が壊れたりします。
147+
Zap のデフォルトはもともとプライバシー優先なので、**触らないでください**。
148+
- **`warp.sqlite`**(および `-wal` / `-shm` のサイドカー)—— schema が上流
149+
Warp に結合しており、Zap の migration が通る保証はありません。
150+
- **Keychain / DPAPI / libsecret のエントリ** —— Warp の bundle / service 名に
151+
紐付いており、Zap からは利用できません。
152+
153+
### 手順
154+
155+
> コピー前に **Warp と Zap を終了**してください。
156+
157+
**macOS / Linux**
158+
159+
```sh
160+
mkdir -p "$HOME/.zap"
161+
for f in settings.toml keybindings.yaml themes workflows launch_configs skills .mcp.json; do
162+
if [ -e "$HOME/.warp/$f" ] && [ ! -e "$HOME/.zap/$f" ]; then
163+
cp -R "$HOME/.warp/$f" "$HOME/.zap/$f"
164+
fi
165+
done
166+
```
167+
168+
**Windows(PowerShell)**
169+
170+
```powershell
171+
$src = "$env:USERPROFILE\.warp"
172+
$dst = "$env:USERPROFILE\.zap"
173+
New-Item -ItemType Directory -Force -Path $dst | Out-Null
174+
175+
$items = @(
176+
'settings.toml',
177+
'keybindings.yaml',
178+
'themes',
179+
'workflows',
180+
'launch_configs',
181+
'skills',
182+
'.mcp.json'
183+
)
184+
185+
foreach ($name in $items) {
186+
$from = Join-Path $src $name
187+
$to = Join-Path $dst $name
188+
if ((Test-Path $from) -and -not (Test-Path $to)) {
189+
Copy-Item -Path $from -Destination $to -Recurse
190+
}
191+
}
192+
```
193+
194+
元の `~/.warp` には一切手を加えません —— Warp 本体はそのまま使い続けられます。
195+
196+
---
197+
198+
## 確認方法
199+
200+
Zap を起動すると、テーマピッカーにカスタムテーマ、キーバインドエディタに
201+
カスタムキーバインド、ワークフローランチャーにカスタムワークフローが見える
202+
はずです。`settings.toml` に存在するキーは、設定 UI 上でも移行元の値が反映
203+
されます。
204+
205+
うまく反映されない場合、原因は上記 7 ファイルのいずれかに含まれています ——
206+
テキストエディタで開いて確認するか、削除して Zap のデフォルトに戻して
207+
ください。
208+
209+
## ロールバック
210+
211+
本書の操作はいずれも破壊的ではありません。コピーしたファイルはどれも Zap が
212+
起動時にデフォルトから再生成できるものです。すべてを元に戻すには:
213+
214+
```sh
215+
# macOS / Linux
216+
rm -rf ~/.zap
217+
```
218+
219+
Windows:
220+
221+
```powershell
222+
Remove-Item -Recurse -Force "$env:USERPROFILE\.zap"
223+
```
224+
225+
`~/.openwarp` と `~/.warp` はいずれも本ガイドからは変更されません。

0 commit comments

Comments
 (0)