gh-code-context

Search for code across GitHub Enterprise and gather comprehensive context including file structure, git history, related files, and usage patterns.

Prerequisites

Verify gh CLI authentication before any search:

gh auth status

Expected: Logged in to target host (github.com or your enterprise host).

If not authenticated, run gh auth login --hostname <host>.

Workflow Decision Tree

User request about code
         │
         ▼
┌─────────────────────┐
│ What type of search?│
└─────────────────────┘
         │
    ┌────┼────┬────────────┐
    ▼    ▼    ▼            ▼
  Find  Find  Find      Understand
  code  usage related   file deeply
    │    │    files        │
    ▼    ▼    ▼            ▼
 search find_ search    get_file_
 _code  usages _code    context
   .sh   .sh    .sh       .sh

Phase 1: Search - Find Relevant Code

Run scripts/search_code.sh to locate code matching the query.

# Basic search across enterprise
./scripts/search_code.sh "functionName" --host github.mycompany.com --org org-name

# With language filter
./scripts/search_code.sh "class AuthService" --host github.mycompany.com --language typescript --limit 20

Options:

• --host: GitHub hostname (e.g., github.mycompany.com for enterprise)
• --org: Organization to search within
• --language: Filter by programming language
• --limit: Max results (default: 10)

For query construction patterns, see references/query-patterns.md.

Phase 2: Expand - Get File Context

Once a relevant file is found, run scripts/get_file_context.sh for deep context.

./scripts/get_file_context.sh owner/repo src/path/to/file.ts --host github.mycompany.com

Returns:

• Full file content
• Directory structure (sibling files)
• Recent commits (last 5)
• Contributors list
• Repository metadata

Phase 3: Trace - Find Usages

To understand how code is used elsewhere, run scripts/find_usages.sh.

# Find all usages of a symbol
./scripts/find_usages.sh "AuthService" --host github.mycompany.com --org org-name

# Exclude the definition file itself
./scripts/find_usages.sh "handleSubmit" --exclude-def --limit 30

Options:

• --exclude-def: Filter out files likely containing the definition
• --limit: Max results (default: 15)

Common Workflows

"Find where X is implemented"

1. Search for definition: ./scripts/search_code.sh "function X" --host github.mycompany.com
2. Get context: ./scripts/get_file_context.sh repo path/file.ts --host github.mycompany.com

"How is Y used across our codebase"

1. Find usages: ./scripts/find_usages.sh "Y" --host github.mycompany.com --org org-name
2. For each significant usage, get context if needed

"Show me the auth/feature code"

1. Search broadly: ./scripts/search_code.sh "auth" --host github.mycompany.com --org org-name --limit 30
2. Identify key files from results
3. Get deep context for main implementation file

"Understand this file's context"

1. Direct context: ./scripts/get_file_context.sh owner/repo path/file.ts --host github.mycompany.com
2. Find usages if it exports functions: ./scripts/find_usages.sh "exportedFunction" --host github.mycompany.com

Enterprise Host Reference

| Host | Usage | |------|-------| | github.com | Public/personal repos (default) | | github.mycompany.com | Enterprise repos (example) |

Always specify --host <your-enterprise-host> for enterprise searches.

Resources

• gh-commands.md - Quick reference for gh CLI commands
• query-patterns.md - Common search query patterns

Troubleshooting

"No results found"

• Check auth: gh auth status
• Verify org name spelling
• Try broader search terms
• Check language filter matches actual file extensions

"Rate limit exceeded"

• Wait 1 minute, then retry
• Use smaller --limit values
• Check: gh api rate_limit

"Could not resolve host"

• Run: gh auth login --hostname <your-enterprise-host>