fetch-github-file

name

fetch-github-file

description

Fetches and displays source code from GitHub file and directory URLs using the gh CLI. Use when the user shares a github.com/owner/repo/blob/... or github.com/owner/repo/tree/... URL, a raw.githubusercontent.com URL, a GitHub Enterprise URL (e.g. github.mycompany.com/...), or explicitly asks to read, fetch, or show the contents of a file or directory on GitHub. Supports file contents, single-line anchors (#L10), line ranges (#L10-L25), directory listings, and shallow repository clones. Don't use for GitHub pull request URLs (/pull/), issue URLs (/issues/), commit URLs (/commit/), release URLs (/releases/), GitHub Actions workflow URLs (/actions/), Gist URLs (gist.github.com), or GitHub wiki URLs (/wiki/). Don't use when the user only wants to discuss, mention, or link to a GitHub project without requesting its file contents.

Fetch GitHub File

Fetch source code from GitHub file and directory URLs using the gh CLI for authenticated access.

Prerequisites

Verify that gh is available and authenticated before proceeding:

gh auth status

If gh is not installed or not authenticated, tell the user: "This skill requires the GitHub CLI (gh). Install it from https://cli.github.com and run gh auth login."

For GitHub Enterprise (GHE) hosts (e.g. github.mycompany.com), pass --hostname github.mycompany.com to all gh commands.

URL Patterns

Parse the GitHub URL to determine what to fetch:

URL Pattern	Type	Action
github.com/owner/repo/blob/ref/path	File	Fetch file contents
github.com/owner/repo/blob/ref/path#L10	File + single line	Fetch file, show line 10 with context
github.com/owner/repo/blob/ref/path#L10-L25	File + range	Fetch file, show lines 10-25
github.com/owner/repo/tree/ref/path	Directory	List directory contents
github.com/owner/repo/tree/ref	Repository root	List root directory
github.com/owner/repo	Repository	List root directory; offer clone for deeper exploration
raw.githubusercontent.com/owner/repo/ref/path	Raw file	Fetch via curl or gh api

URL Parsing

Extract components from a GitHub URL before fetching:

https://github.com/anthropics/claude-code/blob/main/src/index.ts#L10-L25
                   ^^^^^^^^^^^ ^^^^^^^^^^^^ ^^^^ ^^^^ ^^^^^^^^^^^^^ ^^^^^^^^
                   owner       repo         type ref  path          line range

type: "blob" = file, "tree" = directory
ref:  branch name, tag, or full commit SHA
line range: optional; #L10 = single line, #L10-L25 = range

For raw.githubusercontent.com/owner/repo/ref/path, extract owner, repo, ref, and path directly from the path segments.

For bare github.com/owner/repo URLs with no ref, omit the ?ref= parameter entirely from API calls to use the repository's default branch.

Fetching Files

# Fetch file content (returns JSON with base64-encoded content)
# Always quote the URL to prevent shell interpretation of ?
gh api 'repos/{owner}/{repo}/contents/{path}?ref={ref}'

Decode the response using the @base64d jq filter, which is portable across all platforms:

gh api 'repos/{owner}/{repo}/contents/{path}?ref={ref}' --jq '.content | @base64d'

Raw URLs

For raw.githubusercontent.com URLs, use curl (no auth required for public repos) or the API path above:

curl -fsSL 'https://raw.githubusercontent.com/{owner}/{repo}/{ref}/{path}'

Line Anchors and Ranges

If the URL includes #L10 (single line) or #L10-L25 (range):

1. Fetch the full file.
2. Extract and display only the specified lines.
3. Prefix each line with its number.

For a single-line anchor (#L10), display lines 10 ± 5 for context and highlight line 10.

Example output format:

# src/utils/parser.ts (lines 10-25)

10: export function parseUrl(url: string): ParsedUrl {
11:   const match = url.match(GITHUB_PATTERN);
...

Fetching Directories

gh api 'repos/{owner}/{repo}/contents/{path}?ref={ref}' \
  --jq '.[] | "\(.type)\t\(.name)"'

Display as a tree structure showing files and subdirectories. When offering to fetch a specific file from the listing, construct the full path as {parent-path}/{name} so the next API call can be issued without ambiguity.

Cloning Repositories

Clone only when the user explicitly asks for full repo access, or when they need to explore multiple files across the repository. Do not clone when a single file or directory fetch is sufficient.

TEMP_DIR=$(mktemp -d)
gh repo clone {owner}/{repo} "$TEMP_DIR" -- --depth 1 --branch {ref}
echo "Cloned to: $TEMP_DIR"

Use --depth 1 (shallow clone) by default. After cloning, list the root structure and read files as requested. Keep the temp directory path for the remainder of the session.

If --branch {ref} fails because ref is a commit SHA, fetch that specific commit then checkout:

gh repo clone {owner}/{repo} "$TEMP_DIR" -- --depth 1
git -C "$TEMP_DIR" fetch --depth 1 origin {ref}
git -C "$TEMP_DIR" checkout {ref}

Note: git checkout {ref} after a plain --depth 1 clone will fail for arbitrary commit SHAs that are not the shallow tip. The fetch --depth 1 origin {ref} step is required.

Error Handling

• 404: File or path does not exist at the given ref. Verify the path spelling and that the ref (branch/tag/commit) exists.
• 403 / rate limited: Run gh auth status to confirm authentication. If authenticated and still 403, the repo may be private and the user's token may lack the required scope.
• Large file (content is null, download_url is present): The file exceeds the GitHub API 1 MB limit. Fetch via the download_url from the response (pre-signed for private repos, no extra auth needed):

  curl -fsSL '{download_url}'
  

• gh not installed: Inform the user to install from https://cli.github.com.
• gh not authenticated: Run gh auth login or set the GITHUB_TOKEN environment variable.
• GitHub Enterprise: Pass --hostname {ghe-hostname} to all gh commands.

Workflow

1. Verify gh auth status — stop and inform the user if gh is missing or unauthenticated.
2. Parse the URL — extract owner, repo, type (blob/tree/raw), ref, path, and line anchor.
3. Determine fetch strategy based on URL type (file, raw file, directory, or repository root).
4. Fetch via gh api or curl for raw URLs.
5. Format output — file contents with line numbers, or directory listing as a tree.
6. Offer next steps — suggest fetching another file, exploring a directory, or cloning the repo.

Examples

User pastes: https://github.com/anthropics/claude-code/blob/main/src/index.ts#L1-L50

1. Parse: owner=anthropics, repo=claude-code, ref=main, path=src/index.ts, lines=1-50
2. Run: gh api 'repos/anthropics/claude-code/contents/src/index.ts?ref=main' --jq '.content | @base64d'
3. Display lines 1-50 with line numbers.

User pastes: https://github.com/anthropics/claude-code/tree/main/src

1. Parse: owner=anthropics, repo=claude-code, ref=main, path=src
2. Run: gh api 'repos/anthropics/claude-code/contents/src?ref=main' --jq '.[] | "\(.type)\t\(.name)"'
3. Display directory listing; when offering to fetch a file, use full path src/{name}.

User pastes: https://raw.githubusercontent.com/anthropics/claude-code/main/package.json

1. Parse: owner=anthropics, repo=claude-code, ref=main, path=package.json
2. Run: curl -fsSL 'https://raw.githubusercontent.com/anthropics/claude-code/main/package.json'
3. Display file contents.

User pastes: https://github.com/anthropics/claude-code

1. Parse: owner=anthropics, repo=claude-code, no ref, no path
2. Run: gh api 'repos/anthropics/claude-code/contents/' (no ?ref= parameter)
3. Display root directory listing and offer to fetch specific files or clone for deeper exploration.