diff --git a/USER_GUIDE.md b/USER_GUIDE.md index 2db041fef7..8587206fa7 100644 --- a/USER_GUIDE.md +++ b/USER_GUIDE.md @@ -144,15 +144,34 @@ file statuses. Use incremental refreshes after the first run; see ## Shell completion Generate completion scripts with `cdidx --completions `. +The same generator is also available as `cdidx completions `. +Supported shells are Bash, Zsh, Fish, and PowerShell. The generated scripts complete subcommands, flags, and common flag values. `--lang` suggests supported languages, `--kind` suggests symbol/reference kinds, and path-like options such as `--db`, `--path`, and `--output` use shell file completion. +Install the script in the startup file or completion directory for your shell: + +```bash +# Bash: append to your interactive shell startup file +cdidx --completions bash >> ~/.bashrc + +# Zsh: write an fpath entry, then enable compinit from your ~/.zshrc +mkdir -p ~/.zfunc +cdidx --completions zsh > ~/.zfunc/_cdidx +printf '%s\n' 'fpath=(~/.zfunc $fpath)' 'autoload -Uz compinit && compinit' >> ~/.zshrc + +# Fish: write to the standard per-user completions directory +mkdir -p ~/.config/fish/completions +cdidx --completions fish > ~/.config/fish/completions/cdidx.fish +``` + For PowerShell, add the generated `Register-ArgumentCompleter` script to your profile after installing `cdidx`: ```powershell +New-Item -ItemType Directory -Force -Path (Split-Path -Parent $PROFILE) cdidx --completions powershell >> $PROFILE . $PROFILE ``` @@ -2375,6 +2394,40 @@ PATH追加後はターミナルを再起動してください。 cdidx --version ``` +## シェル補完 + +`cdidx --completions ` で補完スクリプトを生成できます。 +同じ generator は `cdidx completions ` でも利用できます。対応シェルは +Bash、Zsh、Fish、PowerShell です。生成されたスクリプトは subcommand、flag、 +よく使う flag value を補完し、`--lang` は対応言語、`--kind` は symbol/reference +kind、`--db` / `--path` / `--output` のような path 系 option は shell の file +completion を使います。 + +使っている shell の startup file または completion directory に保存してください: + +```bash +# Bash: interactive shell startup file に追記 +cdidx --completions bash >> ~/.bashrc + +# Zsh: fpath 用の directory に書き出し、~/.zshrc で compinit を有効化 +mkdir -p ~/.zfunc +cdidx --completions zsh > ~/.zfunc/_cdidx +printf '%s\n' 'fpath=(~/.zfunc $fpath)' 'autoload -Uz compinit && compinit' >> ~/.zshrc + +# Fish: ユーザー別 completion directory に書き出し +mkdir -p ~/.config/fish/completions +cdidx --completions fish > ~/.config/fish/completions/cdidx.fish +``` + +PowerShell では、`cdidx` のインストール後に生成された +`Register-ArgumentCompleter` script を profile に追加します: + +```powershell +New-Item -ItemType Directory -Force -Path (Split-Path -Parent $PROFILE) +cdidx --completions powershell >> $PROFILE +. $PROFILE +``` + ## クイックスタート ### プロジェクトをインデックス diff --git a/changelog.d/unreleased/1639.docs.md b/changelog.d/unreleased/1639.docs.md new file mode 100644 index 0000000000..9e139d81b7 --- /dev/null +++ b/changelog.d/unreleased/1639.docs.md @@ -0,0 +1,17 @@ +--- +category: docs +issues: + - 1639 +affected: + - src/CodeIndex/Cli/ConsoleUi.cs + - USER_GUIDE.md + - tests/CodeIndex.Tests/ConsoleUiTests.cs +--- + +## English + +- **Shell completions are now discoverable from help and the user guide (#1639)** — `cdidx --help` now advertises both completion entry points and all supported shells, while `USER_GUIDE.md` includes Bash, Zsh, Fish, and PowerShell install snippets. + +## 日本語 + +- **シェル補完を help と user guide から見つけられるようにしました (#1639)** — `cdidx --help` が補完用 entry point と対応 shell を案内し、`USER_GUIDE.md` に Bash / Zsh / Fish / PowerShell の install 例を追加しました。 diff --git a/src/CodeIndex/Cli/ConsoleUi.cs b/src/CodeIndex/Cli/ConsoleUi.cs index 2bf4cce6d8..ee3a0a34ba 100644 --- a/src/CodeIndex/Cli/ConsoleUi.cs +++ b/src/CodeIndex/Cli/ConsoleUi.cs @@ -94,6 +94,7 @@ private static readonly (string Command, string Usage)[] CommandUsageLines = ("batch", "cdidx batch [--db ] # reads JSON string arrays from stdin, one query command per line"), ("mcp", "cdidx mcp [--db ]"), ("completions", "cdidx completions "), + ("--completions", "cdidx --completions "), ("license", "cdidx license"), ]; @@ -647,6 +648,7 @@ public static void PrintUsage(bool showBanner = true) Console.WriteLine(" languages List supported languages and their capabilities"); Console.WriteLine(" batch Run newline-delimited JSON query commands with one DB connection"); Console.WriteLine(" mcp Start MCP server (for AI tools: Claude, Cursor, etc.)"); + Console.WriteLine(" completions Generate shell completions for bash, zsh, fish, or PowerShell"); Console.WriteLine(" license Show licensing, trademark, and commercial-use summary"); Console.WriteLine(); Console.WriteLine("Index and update options:"); @@ -676,7 +678,7 @@ public static void PrintUsage(bool showBanner = true) Console.WriteLine(" --help, -h Show this help message"); Console.WriteLine(" --version, -V Show version information"); Console.WriteLine(" --license Show licensing, trademark, and commercial-use summary"); - Console.WriteLine(" --completions Generate shell completions (bash, zsh, fish)"); + Console.WriteLine(" --completions Generate shell completions (bash, zsh, fish, powershell)"); Console.WriteLine(); Console.WriteLine("Update workflows:"); Console.WriteLine(" Use --commits with a project path after normal commits; git diff sees rename/delete paths too."); @@ -770,6 +772,7 @@ public static void PrintUsage(bool showBanner = true) Console.WriteLine(" cdidx files --since 2024-01-01 Files modified since a date"); Console.WriteLine(" cdidx status --json DB stats as JSON"); Console.WriteLine(" cdidx languages Show supported languages"); + Console.WriteLine(" cdidx --completions zsh > ~/.zfunc/_cdidx Generate a zsh completion script"); Console.WriteLine(" cdidx license Show licensing and commercial-use terms"); } diff --git a/tests/CodeIndex.Tests/ConsoleUiTests.cs b/tests/CodeIndex.Tests/ConsoleUiTests.cs index 3a5f32e101..e506fbf2f2 100644 --- a/tests/CodeIndex.Tests/ConsoleUiTests.cs +++ b/tests/CodeIndex.Tests/ConsoleUiTests.cs @@ -64,6 +64,8 @@ public void PrintUsage_WithoutBanner_HidesAsciiArtAndEasterEggFlags() Assert.Contains("cdidx backfill-fold [--db ] [--json]", output); Assert.Contains("cdidx optimize [--db ] [--json]", output); Assert.Contains("cdidx license", output); + Assert.Contains("cdidx completions ", output); + Assert.Contains("cdidx --completions ", output); Assert.Contains("cdidx references |--query |-- ", output); Assert.Contains("cdidx callers |--query |-- ", output); Assert.Contains("cdidx callees |--query |-- ", output); @@ -117,6 +119,9 @@ public void PrintUsage_WithoutBanner_HidesAsciiArtAndEasterEggFlags() Assert.Contains("cdidx impact FolderDiffService --json Type query may return heuristic file-level dependency hints", output); Assert.Contains("license Show licensing, trademark, and commercial-use summary", output); Assert.Contains("--license Show licensing, trademark, and commercial-use summary", output); + Assert.Contains("completions Generate shell completions for bash, zsh, fish, or PowerShell", output); + Assert.Contains("--completions Generate shell completions (bash, zsh, fish, powershell)", output); + Assert.Contains("cdidx --completions zsh > ~/.zfunc/_cdidx Generate a zsh completion script", output); Assert.Contains("cdidx license Show licensing and commercial-use terms", output); Assert.DoesNotContain("Easter eggs", output); Assert.DoesNotContain("--sushi", output); @@ -147,6 +152,8 @@ public void PrintUsage_QueryLinesMatchImplementedOptions() Assert.Contains("cdidx hotspots [--db ] [--json] [--verbose] [--limit ] [--kind ] [--visibility ] [--exclude-visibility ] [--lang ] [--path ] [--exclude-path ] [--exclude-tests] [--count]", output); Assert.Contains("cdidx unused [--db ] [--json] [--verbose] [--limit ] [--kind ] [--visibility ] [--exclude-visibility ] [--lang ] [--path ] [--exclude-path ] [--exclude-tests] [--count]", output); Assert.Contains("cdidx license", output); + Assert.Contains("cdidx completions ", output); + Assert.Contains("cdidx --completions ", output); } [Theory]