From c7e90ce0286e6bbf9f4a4409d35f05684429c5cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20HOUZ=C3=89?= Date: Sun, 23 Aug 2026 14:24:43 +0200 Subject: [PATCH 1/4] Document quote escaping and fix misleading regex-hint example (#150) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add a new "Searching for a literal quote character" section to docs/usage/search-syntax.md explaining GitHub's double-escaping syntax (shell + GitHub), the difference between balanced and unbalanced raw quotes, and the new local validation error introduced by #149. - Replace the --regex-hint '"axios"' example: wrapping a single word in quotes has zero filtering effect on GitHub's side (verified against the live API), so it was actively misleading. The new example uses a pattern with no literal characters at all, which genuinely requires a hint. - Update the semver/version-audit example note that the double quotes in the pattern are now preserved and escaped automatically instead of being dropped (see #147) — this vitepress landing-page use case previously demonstrated a command that, before this epic's fixes, did not actually behave as advertised. Closes #150 --- docs/.vitepress/theme/UseCaseTabs.vue | 2 +- docs/usage/search-syntax.md | 48 ++++++++++++++++++++++++--- 2 files changed, 45 insertions(+), 5 deletions(-) diff --git a/docs/.vitepress/theme/UseCaseTabs.vue b/docs/.vitepress/theme/UseCaseTabs.vue index 4d3b274..ae0ab05 100644 --- a/docs/.vitepress/theme/UseCaseTabs.vue +++ b/docs/.vitepress/theme/UseCaseTabs.vue @@ -55,7 +55,7 @@ const USE_CASES: UseCase[] = [ label: "Semver / version audit", headline: "Which repos are pinned to a vulnerable minor version?", description: - "Use regex syntax to target a precise version range — something a plain keyword search cannot do. Find every repo still locked to axios 1.x, react 17.x, or any other outdated pin, then export the list to a migration issue.", + "Use regex syntax to target a precise version range, something a plain keyword search cannot do. Find every repo still locked to axios 1.x, react 17.x, or any other outdated pin, then export the list to a migration issue. The CLI automatically escapes the double quotes in the pattern so the search stays precise instead of matching every unrelated mention of axios or react.", command: `github-code-search query '/"axios": "1\\./' --org my-org`, }, ]; diff --git a/docs/usage/search-syntax.md b/docs/usage/search-syntax.md index bb3b4bc..b863a5f 100644 --- a/docs/usage/search-syntax.md +++ b/docs/usage/search-syntax.md @@ -81,13 +81,14 @@ github-code-search "password= language:TypeScript NOT filename:test" --org fulll `github-code-search` supports regex syntax using the `/pattern/flags` notation, just like the GitHub web UI. -Because the GitHub Code Search API does not natively support regex, the CLI automatically extracts a representative literal term from the regex to send to the API, then filters the returned results locally with the full pattern. In most cases this is fully transparent. +Because the GitHub Code Search API does not natively support regex, the CLI automatically extracts a representative literal term from the regex to send to the API, then filters the returned results locally with the full pattern. In most cases this is fully transparent, including patterns that contain literal `"` characters, which the CLI escapes automatically using GitHub's own quote-escaping syntax (see [Searching for a literal quote character](#searching-for-a-literal-quote-character) below). ```bash # Imports using the axios module (any quote style) github-code-search "/from.*['\"\`]axios/" --org fulll -# Axios dependency in package.json (any semver prefix) +# Axios dependency in package.json (any semver prefix) — the double quotes in +# the pattern are preserved and escaped automatically for the GitHub API github-code-search '/"axios": "[~^]?[0-9]"/ filename:package.json' --org fulll # Old library require() calls @@ -110,20 +111,59 @@ If the extracted term is very short (fewer than 3 characters), the CLI will exit ⚠ Regex mode — No meaningful search term could be extracted from the regex pattern. Use --regex-hint to specify the term to send to the GitHub API. ``` +This happens when the pattern has no literal characters at all, for example a pure version-number match: + +```bash +github-code-search '/[0-9]+\.[0-9]+\.[0-9]+/' --org fulll +``` + Use `--regex-hint` to override the API search term while still applying the full regex filter locally: ```bash -github-code-search '/"axios":\s*"[~^]?[0-9]/ filename:package.json' \ +github-code-search '/[0-9]+\.[0-9]+\.[0-9]+/ filename:package.json' \ --org fulll \ - --regex-hint '"axios"' + --regex-hint version ``` +::: tip Quoting a single word has no filtering effect +Wrapping a single word in double quotes (e.g. `--regex-hint '"axios"'`) does **not** narrow the +GitHub search — GitHub treats a one-word quoted phrase exactly like the bare word. Quotes only +matter for multi-word phrases (`"feature flag"`) or when you need to search for the literal `"` +character itself, see below. +::: + ::: warning API coverage The GitHub Code Search API returns **at most 1,000 results** per query. The regex filter is applied to those results; results beyond the API cap can never be seen. Refine the query with qualifiers (`language:`, `path:`, `filename:`) to keep the result set small. ::: +## Searching for a literal quote character + +GitHub's query syntax treats `"` as a phrase delimiter, not a literal character. To search for an actual quote character (for example to precisely match a `package.json` dependency line like `"react": "18.2.0"`), escape it for **both** your shell and GitHub: + +```bash +github-code-search '"\"react\": \""' --org fulll +``` + +- The outer single quotes protect the whole argument from your shell. +- The `\"` sequences are GitHub's own escape syntax for a literal quote character inside an exact phrase. + +If you instead pass raw, unescaped quotes, two things can happen: + +- **An even number of quotes** (e.g. `"react": `) is valid GitHub syntax, but GitHub silently strips the quotes and treats the query as separate terms, so you get broader results than expected, not an error. +- **An odd number of quotes** (e.g. `"react": "`) is rejected by GitHub with an opaque `422 ERROR_TYPE_QUERY_PARSING_FATAL` error. `github-code-search` detects this locally and fails fast with an actionable message before ever calling the API: + +```text +Error: Unbalanced double quotes in query: "\"react\": \"". GitHub rejects this with a query +parsing error. To search for a literal quote character, escape it for both your shell and +GitHub, e.g.: github-code-search '"\"react\": \""' --org myorg +``` + +::: warning Shell escaping consumes backslashes too +Typing `"\"react\": \""` directly (double-quoted at the shell level) does **not** work: your shell resolves `\"` to a literal `"` *before* the CLI ever sees it, so the program receives the same unbalanced `"react": "` string as if you had typed no backslashes at all. Always wrap the whole argument in **single** quotes so the backslashes reach GitHub unchanged, as in the example above. +::: + ## API limits The GitHub Code Search API returns at most **1,000 results** per query. If your query returns more, refine it with qualifiers (especially `language:` or `path:`) to stay below the limit. From 032234018895c2067767b46ab5583b2e3e9b012f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20HOUZ=C3=89?= Date: Sun, 23 Aug 2026 14:25:51 +0200 Subject: [PATCH 2/4] Fix markdown formatting (oxfmt) --- docs/usage/search-syntax.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/search-syntax.md b/docs/usage/search-syntax.md index b863a5f..d574634 100644 --- a/docs/usage/search-syntax.md +++ b/docs/usage/search-syntax.md @@ -161,7 +161,7 @@ GitHub, e.g.: github-code-search '"\"react\": \""' --org myorg ``` ::: warning Shell escaping consumes backslashes too -Typing `"\"react\": \""` directly (double-quoted at the shell level) does **not** work: your shell resolves `\"` to a literal `"` *before* the CLI ever sees it, so the program receives the same unbalanced `"react": "` string as if you had typed no backslashes at all. Always wrap the whole argument in **single** quotes so the backslashes reach GitHub unchanged, as in the example above. +Typing `"\"react\": \""` directly (double-quoted at the shell level) does **not** work: your shell resolves `\"` to a literal `"` _before_ the CLI ever sees it, so the program receives the same unbalanced `"react": "` string as if you had typed no backslashes at all. Always wrap the whole argument in **single** quotes so the backslashes reach GitHub unchanged, as in the example above. ::: ## API limits From 2919483c83d6dea4f2086d31d991008dcc9ccb7f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20HOUZ=C3=89?= Date: Sun, 23 Aug 2026 16:53:44 +0200 Subject: [PATCH 3/4] Potential fix for pull request finding MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Sébastien HOUZÉ --- docs/usage/search-syntax.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/search-syntax.md b/docs/usage/search-syntax.md index d574634..df37b89 100644 --- a/docs/usage/search-syntax.md +++ b/docs/usage/search-syntax.md @@ -143,7 +143,7 @@ query with qualifiers (`language:`, `path:`, `filename:`) to keep the result set GitHub's query syntax treats `"` as a phrase delimiter, not a literal character. To search for an actual quote character (for example to precisely match a `package.json` dependency line like `"react": "18.2.0"`), escape it for **both** your shell and GitHub: ```bash -github-code-search '"\"react\": \""' --org fulll +github-code-search '"\"react\": \""' --org myorg ``` - The outer single quotes protect the whole argument from your shell. From 8318f4a1bc1b427aabc8c605f3982d4f8115fb1b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20HOUZ=C3=89?= Date: Sun, 23 Aug 2026 16:54:39 +0200 Subject: [PATCH 4/4] Potential fix for pull request finding MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Sébastien HOUZÉ --- docs/usage/search-syntax.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/search-syntax.md b/docs/usage/search-syntax.md index df37b89..8034118 100644 --- a/docs/usage/search-syntax.md +++ b/docs/usage/search-syntax.md @@ -140,7 +140,7 @@ query with qualifiers (`language:`, `path:`, `filename:`) to keep the result set ## Searching for a literal quote character -GitHub's query syntax treats `"` as a phrase delimiter, not a literal character. To search for an actual quote character (for example to precisely match a `package.json` dependency line like `"react": "18.2.0"`), escape it for **both** your shell and GitHub: +GitHub's query syntax treats `"` as a phrase delimiter, not a literal character. To search for an actual quote character (for example to match a `package.json` dependency key/value prefix like `"react": "`), escape it for **both** your shell and GitHub: ```bash github-code-search '"\"react\": \""' --org myorg