fix: treat empty string as "not set" for optional fields and add SSH docs (#130)

## Changes
- Empty strings in optional fields (service, sshKeyPath, sshHost, gpgKeyId)
  are now treated as "not set" instead of triggering validation errors
- Added configSchema.test.ts with 68 comprehensive test cases
- Added SSH interaction documentation to README (en, ja):
  - SSH Key Management Details
  - Interaction with Existing SSH Config
  - Why IdentitiesOnly yes?
- Updated version to 0.11.1

🖥️ IDE: [Cursor](https://cursor.sh)
🔌 Extension: [Claude Code](https://claude.ai/download)


Model-Raw: claude-opus-4-5-20251101

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: nullvariant

extensions/git-id-switcher/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.1] - 2026-01-12
+
+### Fixed
+
+- **Empty String Validation**
+  - Empty strings in optional fields (`service`, `sshKeyPath`, `sshHost`, `gpgKeyId`) are now treated as "not set" instead of triggering validation errors
+  - This eliminates unnecessary warnings when using default settings
+  - Required fields (`id`, `name`, `email`) still correctly reject empty strings
+
+### Added
+
+- **configSchema Tests**
+  - Added comprehensive test suite for `configSchema.ts` (68 test cases)
+  - Covers empty string handling, malicious value rejection, format validation, and edge cases
+  - Test coverage improved to 92.99%
+
+### Documentation
+
+- **SSH Interaction Sections (en, ja)**
+  - Added "SSH Key Management Details" section explaining ssh-agent commands
+  - Added "Interaction with Existing SSH Config" section for compatibility guide
+  - Added "Why `IdentitiesOnly yes`?" section with recommended configuration
+
 ## [0.11.0] - 2026-01-11
 
 ### Security

extensions/git-id-switcher/README.md

@@ -408,6 +408,54 @@ When you switch identities, the extension does (in order):
 Local settings are per-repository, so they don't automatically apply to submodules.
 That's why this extension provides submodule propagation (see "Advanced: Submodule Support" for details).
 
+### SSH Key Management Details
+
+Git ID Switcher manages SSH keys through `ssh-agent`:
+
+| Operation  | Command                   |
+| ---------- | ------------------------- |
+| Add key    | `ssh-add <keyPath>`       |
+| Remove key | `ssh-add -d <keyPath>`    |
+| List keys  | `ssh-add -l`              |
+
+**Important:** This extension does **NOT** modify `~/.ssh/config`. You need to set up your SSH config manually (see Step 2 in "Quick Start").
+
+### Interaction with Existing SSH Config
+
+If you already have SSH configuration, Git ID Switcher works alongside it:
+
+| Your Setup                               | Git ID Switcher Behavior                                        |
+| ---------------------------------------- | --------------------------------------------------------------- |
+| `~/.ssh/config` with `IdentityFile`      | Both can be used; use `IdentitiesOnly yes` to prevent conflicts |
+| `GIT_SSH_COMMAND` environment variable   | Git uses your custom SSH command; ssh-agent still works         |
+| `git config core.sshCommand`             | Same as above                                                   |
+| direnv with SSH-related env vars         | Works alongside; ssh-agent operates independently               |
+
+**Recommended:** Always use `IdentitiesOnly yes` in your SSH config. This prevents SSH from trying multiple keys.
+
+### Why `IdentitiesOnly yes`?
+
+Without this setting, SSH may try keys in this order:
+
+1. Keys loaded in ssh-agent (managed by Git ID Switcher)
+2. Keys specified in `~/.ssh/config`
+3. Default keys (`~/.ssh/id_rsa`, `~/.ssh/id_ed25519`, etc.)
+
+This can cause authentication failures or unintended key usage.
+
+With `IdentitiesOnly yes`, SSH uses **only the specified key**. This ensures the key you configured in Git ID Switcher is used reliably.
+
+```ssh-config
+# Recommended configuration
+Host github-work
+    HostName github.com
+    User git
+    IdentityFile ~/.ssh/id_ed25519_work
+    IdentitiesOnly yes  # ← This line is important
+```
+
+With this configuration, connections to the `github-work` host will only use `~/.ssh/id_ed25519_work`, and no other keys will be tried.
+
 ---
 
 ## Advanced: Submodule Support

extensions/git-id-switcher/docs/i18n/en/README.md

@@ -404,6 +404,54 @@ When you switch identities, the extension does (in order):
 Local settings are per-repository, so they don't automatically apply to submodules.
 That's why this extension provides submodule propagation (see "Advanced: Submodule Support" for details).
 
+### SSH Key Management Details
+
+Git ID Switcher manages SSH keys through `ssh-agent`:
+
+| Operation  | Command                   |
+| ---------- | ------------------------- |
+| Add key    | `ssh-add <keyPath>`       |
+| Remove key | `ssh-add -d <keyPath>`    |
+| List keys  | `ssh-add -l`              |
+
+**Important:** This extension does **NOT** modify `~/.ssh/config`. You need to set up your SSH config manually (see Step 2 in "Quick Start").
+
+### Interaction with Existing SSH Config
+
+If you already have SSH configuration, Git ID Switcher works alongside it:
+
+| Your Setup                               | Git ID Switcher Behavior                                        |
+| ---------------------------------------- | --------------------------------------------------------------- |
+| `~/.ssh/config` with `IdentityFile`      | Both can be used; use `IdentitiesOnly yes` to prevent conflicts |
+| `GIT_SSH_COMMAND` environment variable   | Git uses your custom SSH command; ssh-agent still works         |
+| `git config core.sshCommand`             | Same as above                                                   |
+| direnv with SSH-related env vars         | Works alongside; ssh-agent operates independently               |
+
+**Recommended:** Always use `IdentitiesOnly yes` in your SSH config. This prevents SSH from trying multiple keys.
+
+### Why `IdentitiesOnly yes`?
+
+Without this setting, SSH may try keys in this order:
+
+1. Keys loaded in ssh-agent (managed by Git ID Switcher)
+2. Keys specified in `~/.ssh/config`
+3. Default keys (`~/.ssh/id_rsa`, `~/.ssh/id_ed25519`, etc.)
+
+This can cause authentication failures or unintended key usage.
+
+With `IdentitiesOnly yes`, SSH uses **only the specified key**. This ensures the key you configured in Git ID Switcher is used reliably.
+
+```ssh-config
+# Recommended configuration
+Host github-work
+    HostName github.com
+    User git
+    IdentityFile ~/.ssh/id_ed25519_work
+    IdentitiesOnly yes  # ← This line is important
+```
+
+With this configuration, connections to the `github-work` host will only use `~/.ssh/id_ed25519_work`, and no other keys will be tried.
+
 ---
 
 ## Advanced: Submodule Support

extensions/git-id-switcher/docs/i18n/ja/README.md

@@ -404,6 +404,54 @@ Gitの設定には3つのレイヤーがあり、下位の設定を上位が上
 ローカル設定はリポジトリ単位のため、サブモジュールには自動的に適用されません。
 そのため、本拡張機能はサブモジュールへの伝播機能を提供しています（詳細は「上級者向け: サブモジュールサポート」を参照）。
 
+### SSH鍵管理の詳細
+
+Git ID Switcherは`ssh-agent`を通じてSSH鍵を管理します：
+
+| 操作     | 実行コマンド              |
+| -------- | ------------------------- |
+| 鍵を追加 | `ssh-add <keyPath>`       |
+| 鍵を削除 | `ssh-add -d <keyPath>`    |
+| 鍵の一覧 | `ssh-add -l`              |
+
+**重要:** この拡張機能は `~/.ssh/config` を**変更しません**。SSH configの設定は手動で行う必要があります（「クイックスタート」のステップ2を参照）。
+
+### 既存のSSH設定との相互作用
+
+すでにSSH設定がある場合、Git ID Switcherは以下のように動作します：
+
+| あなたの設定                             | Git ID Switcherの動作                                  |
+| ---------------------------------------- | ------------------------------------------------------ |
+| `~/.ssh/config` で `IdentityFile` を指定 | 両方が使用可能；`IdentitiesOnly yes` で競合を防止      |
+| 環境変数 `GIT_SSH_COMMAND` を設定        | カスタムSSHコマンドを使用；ssh-agentは引き続き動作     |
+| `git config core.sshCommand` を設定      | 上記と同様                                             |
+| direnvでSSH関連の環境変数を設定          | 共存可能；ssh-agentは独立して動作                      |
+
+**推奨:** SSH configでは常に `IdentitiesOnly yes` を設定してください。これにより、SSHが複数の鍵を試行することを防ぎます。
+
+### なぜ `IdentitiesOnly yes`？
+
+この設定がない場合、SSHは以下の順序で鍵を試行する可能性があります：
+
+1. ssh-agentに読み込まれた鍵（Git ID Switcherが管理）
+2. `~/.ssh/config` で指定された鍵
+3. デフォルトの鍵（`~/.ssh/id_rsa`, `~/.ssh/id_ed25519` など）
+
+これにより、認証失敗や意図しない鍵の使用が発生する可能性があります。
+
+`IdentitiesOnly yes` を設定すると、SSHは**指定された鍵のみ**を使用します。これにより、Git ID Switcherで設定した鍵が確実に使用されます。
+
+```ssh-config
+# 推奨される設定
+Host github-work
+    HostName github.com
+    User git
+    IdentityFile ~/.ssh/id_ed25519_work
+    IdentitiesOnly yes  # ← この行が重要
+```
+
+この設定により、`github-work` ホストへの接続時には `~/.ssh/id_ed25519_work` のみが使用され、他の鍵は試行されません。
+
 ---
 
 ## 上級者向け: サブモジュールサポート

extensions/git-id-switcher/package-lock.json

@@ -2,7 +2,7 @@
   "name": "git-id-switcher",
   "displayName": "%extension.displayName%",
   "description": "%extension.description%",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "publisher": "nullvariant",
   "icon": "images/icon.png",
   "engines": {