gh-search-code
Skill9 starsChanged 12 months agoMITView on GitHub
Use when searching code across GitHub repositories - provides syntax for file extensions, filenames, languages, sizes, exclusions, and using -w flag for regex search via web interface
In this repository8 other files it gives its agents.
- gh-cli-setupSkill
- gh-search-commitsSkill
- gh-search-issuesSkill
- gh-search-prsSkill
- gh-search-reposSkill
- gh-searchSkill
- testing-gh-skillsSkill
- using-gh-cli-searchSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 3 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
Search for code across GitHub repositories using gh search code.
- Distinctive: line 14
Use this skill when searching code across GitHub:
- Very specific: line 49
When using inline query exclusions (negations with -), you MUST use the -- separator:
- Very specific: line 155
CRITICAL: When excluding results, you MUST use query syntax with the -- separator.
- Very specific: line 158
Use the -- separator before your query
- Very specific: line 159
Use -qualifier:value format (dash prefix for negation)
- Distinctive: line 230
Use quotes for comparison operators:
- Very specific: line 296
If gh command not found:
- Distinctive: line 328
Use the web flag when you need:
- Very specific: line 348
Workaround: Use -w/--web to access full GitHub search features
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
GitHub CLI: Search Code
Overview
Search for code across GitHub repositories using gh search code. Important: CLI API uses legacy search engine. For regex and advanced features, use -w flag to open in web browser.
When to Use This Skill
Use this skill when searching code across GitHub:
- Searching for code patterns across multiple repositories
- Finding specific file types or filenames in repos/orgs
- Locating code by language or file size across GitHub
- Searching in specific repositories or organizations
- Need to exclude certain results (requires
--flag) - Need regex search (use
-wto open in browser)
Syntax
gh search code <query> [flags]Key Flags Reference
| Flag | Purpose | Example |
--extension <string> | Filter by file extension | --extension js |
--filename <string> | Target specific filenames | --filename package.json |
--language <string> | Filter by programming language | --language python |
--owner <strings> | Limit to specific owners | --owner microsoft |
-R, --repo <strings> | Search within repository | --repo cli/cli |
--size <string> | Filter by file size (KB) | --size ">100" |
--match <strings> | Search in file or path | --match file or --match path |
-L, --limit <int> | Max results (default: 30) | --limit 100 |
-w, --web | Open in browser | -w |
--json <fields> | JSON output | --json path,repository |
JSON Output Fields
Available fields: path, repository, sha, textMatches, url
Exclusion Syntax (Critical!)
When using inline query exclusions (negations with -), you MUST use the -- separator:
✅ Correct: gh search code -- "search-terms -qualifier:value"
❌ Wrong: gh search code "search-terms" --flag=-value
❌ Wrong: gh search code "search-terms" --flag=!value
❌ Wrong: gh search code "search-terms" --filename="!test"
Examples:
gh search code -- "function -filename:test"(exclude files named "test")gh search code -- "import -language:javascript"(exclude language)gh search code -- "config -path:vendor"(exclude vendor directories)gh search code -- "TODO -extension:md"(exclude extension)
Why the -- separator is required:
The -- tells the shell to stop parsing flags and treat everything after it as arguments. Without it, -qualifier:value inside quotes may be misinterpreted.
Understanding -filename: vs -path: Qualifiers
Critical Distinction: These qualifiers have different matching behaviors:
| Qualifier | Matches | Use When |
-filename: | Filename only (e.g., test.js, utils_test.py) | Excluding files by their name pattern |
-path: | Full file path (e.g., src/test/file.js, lib/testing/util.js) | Excluding directory paths or path segments |
When to Use Each
Use -filename: when:
- User says "exclude test files" → means files named with "test"
- Targeting files by their name pattern
- Examples:
test.js,config_test.py,utils.test.ts
Use -path: when:
- User says "exclude test directories" → means directories containing "test"
- Targeting files in specific directory paths
- Examples:
tests/,__test__/,src/test/,lib/testing/
Matching Examples
-filename:test matches:
test.js✅utils_test.py✅test_helper.rb✅src/file.js❌ (doesn't contain "test" in filename)tests/utils.js❌ (filename is "utils.js", not "test")
-path:test matches:
tests/utils.js✅ (path contains "test")src/test/file.js✅ (path contains "test")lib/testing/helper.py✅ (path contains "test")test.js✅ (path includes filename)src/utils.js❌ (path doesn't contain "test")
Practical Examples
Exclude files by name:
# User: "Find functions but NOT in test files"
gh search code -- "function -filename:test"
# Excludes: test.js, utils_test.py, config.test.ts
# Includes: tests/utils.js (filename is "utils.js", not "test")Exclude directories:
# User: "Find config but NOT in test directories"
gh search code -- "config -path:test"
# Excludes: tests/config.js, src/test/config.py, __test__/setup.js
# Includes: config_test.js (not in test directory)Combine both qualifiers:
# User: "Exclude both test files AND test directories"
gh search code -- "function -filename:test -path:test"
# Excludes: test.js, tests/utils.js, src/test/file.js, utils_test.pyCritical Syntax Rules
When to Use Flag Syntax vs Query Syntax
Decision Tree:
Does your search include:
- Any exclusions (NOT, minus, without, except)? → Use Query Syntax with `--`
- Complex boolean logic (OR, AND)? → Use Query Syntax with `--`
Otherwise:
- Simple positive filters only? → Use Flag SyntaxFlag Syntax (for positive filters):
gh search code "import" --language python --extension pyQuery Syntax with -- (required for exclusions):
gh search code -- "function -filename:test.js -language:javascript"⚠️ NEVER mix both syntaxes in a single command!
1. Exclusions and Negations
CRITICAL: When excluding results, you MUST use query syntax with the -- separator.
Exclusion Syntax Rules:
- Use the
--separator before your query - Use
-qualifier:valueformat (dash prefix for negation) - Quote the entire query string
Examples:
Single exclusion:
# Exclude files named "test.js"
gh search code -- "function -filename:test.js"
# Exclude specific language
gh search code -- "import -language:javascript"
# Exclude vendor directories
gh search code -- "config -path:vendor"Multiple exclusions:
# Exclude multiple filenames
gh search code -- "function -filename:test.js -filename:spec.js"
# Exclude language and test directories
gh search code -- "TODO -language:go -path:test"
# Exclude multiple languages
gh search code -- "class -language:java -language:kotlin"Combine with positive filters using flags:
# Wrong - mixing syntaxes:
gh search code "function" --language python -filename:test # ❌
# Correct - use query syntax for everything when excluding:
gh search code -- "function language:python -filename:test" # ✅PowerShell exclusions:
# Use --% to prevent PowerShell parsing
gh --% search code -- "function -filename:test.js"Common Exclusion Patterns:
| User Request | Command | Qualifier Used |
| "Find code but not in test files" | gh search code -- "function -filename:test" | -filename: (matches file names) |
| "Code excluding test directories" | gh search code -- "function -path:test" | -path: (matches directory paths) |
| "Code excluding specific language" | gh search code -- "import -language:javascript" | -language: |
| "Code not in vendor/node_modules dirs" | gh search code -- "config -path:vendor -path:node_modules" | -path: (matches directories) |
| "Functions excluding test and spec files" | gh search code -- "function -filename:test -filename:spec" | -filename: (matches file names) |
| "Code excluding large files" | gh search code -- "class -size:>500" | -size: |
| "Code not in specific extension" | gh search code -- "TODO -extension:md -extension:txt" | -extension: |
| "Code excluding example/doc directories" | gh search code -- "api -path:examples -path:docs" | -path: (matches directories) |
2. Quoting Rules
Multi-word search:
gh search code "error handling"Complex queries with qualifiers:
gh search code "TODO in:file" --language javascript3. Size Comparisons
Use quotes for comparison operators:
gh search code "import" --size ">50" --language pythonCommon Use Cases
Search for function patterns:
gh search code "async function" --language typescriptFind configuration files:
gh search code "database" --filename config.json --owner myorgSearch in specific repo:
gh search code "TODO" --repo owner/repo --language goExclude files named with "test":
gh search code -- "function -filename:test"Exclude test directories:
gh search code -- "function -path:test"Search by file size:
gh search code "import" --size "100..500" --language pythonUse regex (via web):
# Open in browser for regex support
gh search code "function.*test" --language javascript -w
# Web UI allows: /function.*test/ or /class\s+\w+/Build complex query, refine in web:
# Start with CLI filters, finish with regex in browser
gh search code --owner microsoft --language typescript -wCommon Mistakes
| Mistake | Problem | Fix |
--extension="NOT js" or --language=-python | Flag syntax doesn't support negation | Use query: -- "-extension:js" or -- "-language:python" |
gh search code import -language:js | -language interpreted as flag | Use --: gh search code -- "import -language:js" |
"function NOT language:js" | NOT keyword doesn't work | Use -: -- "function -language:js" |
Mixing syntaxes: --language python "code -filename:test" | Can't mix flags with query qualifiers | Use query for all: -- "code language:python -filename:test" |
| Not quoting multi-word queries | Searches separately | Quote: "error handling" |
| Forgetting quotes on comparisons | Shell interprets > | Quote: --size ">100" |
Using -filename inline without -- | Parsed as flag | Use --: -- "code -filename:test" |
| Trying regex via CLI | CLI API doesn't support regex | Use -w flag: gh search code "pattern" -w |
PowerShell without --% | Breaks with exclusions | Add: gh --% |
Installation Check
If gh command not found:
# Check if gh is installed
which gh
# If not installed, see: https://cli.github.com/manual/installationIf not authenticated:
# Authenticate with GitHub
gh auth loginWeb Browser Flag (-w/--web)
Important workaround for advanced features:
The -w/--web flag opens your search in GitHub's web interface, which supports features not available via CLI API:
Regex Search (Web Only)
# This opens in browser where you can use regex
gh search code "function.*test" --language javascript -w
# In the web UI, you can then modify to use regex syntax:
# /function.*test/ language:javascriptWhen to Use -w
Use the web flag when you need:
- Regex patterns -
/pattern/syntax for complex matching - Advanced filters - Newer GitHub search features
- Visual browsing - Easier to explore results visually
- Better results - Web uses newer search engine
Combining CLI + Web
# Build query with CLI, open in web for regex
gh search code --language python --repo myorg/myrepo -w
# Then add regex pattern in web UILimitations (CLI API)
- Powered by legacy GitHub search engine
- Results may differ from github.com
- Regex search not available via CLI (use
-wflag instead) - Some advanced features may not work
- Workaround: Use
-w/--webto access full GitHub search features
Related
- GitHub search syntax: https://docs.github.com/search-github/searching-on-github/searching-code
- For searching other resources:
gh-search-issues,gh-search-prs,gh-search-repos,gh-search-commits
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

