iframe-proxy

babakks · 2026-06-03T11:33:51Z

Summary

This PR adds two new (preview) commands for reading repository contents without cloning.

`gh repo read-file`

gh repo read-file <path> [--ref <ref>] [--output <path>] [--clobber] [--unsafe] [--json <fields>] [--jq <expression>] [--template <string>] [--repo <owner/repo>]

Reads a single file from a repository and writes it to stdout (or to a file with --output).

`gh repo read-dir`

gh repo read-dir [<path>] [--ref <ref>] [--json <fields>] [--jq <expression>] [--template <string>] [--repo <owner/repo>]

Lists the entries of a directory in a repository, showing each entry's type, name, and size.

Both commands are marked preview, default to the current repository's default branch (overridable with --ref), and support --json/--jq/--template for scripting.

Test plan

You can verify the command behaviour via acceptance tests and the following examples.

The commands below target public repositories so they can be run as-is.

`gh repo read-file`

# Read a file to stdout
gh repo read-file README.md --repo cli/cli

# Read from a specific tag/branch/commit
gh repo read-file README.md --ref v2.0.0 --repo cli/cli

# Write to a file, then confirm --clobber is required to overwrite
gh repo read-file README.md --output /tmp/readme.md --repo cli/cli
gh repo read-file README.md --output /tmp/readme.md --repo cli/cli            # should error: already exists
gh repo read-file README.md --output /tmp/readme.md --clobber --repo cli/cli  # should succeed

# JSON output, with jq and template
gh repo read-file README.md --json path,size,type --repo cli/cli
gh repo read-file README.md --json path,size --jq '.size' --repo cli/cli
gh repo read-file README.md --template '{{.path}} ({{.size}} bytes){{"\n"}}' --repo cli/cli

# Error: path does not exist
gh repo read-file does/not/exist.md --repo cli/cli

`gh repo read-dir`

# List the repository root
gh repo read-dir --repo cli/cli

# List a subdirectory (note executables render as `file*`)
gh repo read-dir script --repo cli/cli

# Mixed entry types in one listing: regular files, a symlink (RelNotes),
# and a submodule (sha1collisiondetection)
gh repo read-dir --repo git/git

# List from a specific tag/branch/commit
gh repo read-dir docs --ref v2.0.0 --repo cli/cli

# Non-TTY / scriptable output (tab separated)
gh repo read-dir script --repo cli/cli | cat

# JSON output, with jq and template
gh repo read-dir script --json name,type,mode,modeOctal --repo cli/cli
gh repo read-dir script --json name,type --jq '.entries[] | select(.type=="file") | .name' --repo cli/cli
gh repo read-dir --template '{{range .entries}}{{.type}}: {{.name}}{{"\n"}}{{end}}' --repo cli/cli

# Error: path points to a file, not a directory
gh repo read-dir README.md --repo cli/cli

# Error: path or ref does not exist
gh repo read-dir nope/nope --repo cli/cli

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Signed-off-by: Babak K. Shandiz <babakks@github.com>

…ands Signed-off-by: Babak K. Shandiz <babakks@github.com>

Signed-off-by: Babak K. Shandiz <babakks@github.com>

Copilot

Pull request overview

This PR introduces two new preview gh repo subcommands—read-file and read-dir—to fetch repository file and directory contents over the GitHub API without cloning, with support for scriptable output (--json/--jq/--template) and acceptance coverage.

Changes:

Add gh repo read-file for fetching a single file’s metadata/content and optionally writing it to disk.
Add gh repo read-dir for listing a repository directory (TTY table / non-TTY TSV / JSON).
Add a shared internal/text.FormatSize helper and acceptance fixtures for both commands.

Show a summary per file

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 11/11 changed files
Comments generated: 10

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

babakks · 2026-06-16T14:13:17Z

I just pushed a commit to add the new commands in gh's skill file.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Signed-off-by: Babak K. Shandiz <babakks@github.com>

Sign in to view

+		{1572864, "1.5 MB"},
+		{5242880, "5.0 MB"},
+		{1073741824, "1.0 GB"},
+		{1610612736, "1.5 GB"},


Avoids an out-of-range panic for byte counts at or above one exabyte, which fit within int64, and lets the function accept the full int64 range. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

BagToad

Looks pretty good! 🔥 🚀

Signed-off-by: Babak K. Shandiz <babakks@github.com>

babakks and others added 12 commits June 2, 2026 23:17

feat(repo): add read-file command

d5b0a11

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

test(repo read-file): add tests for read-file command

f2db9e7

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

chore(internal/text): move FormatSize from repo read-file

a88a8ba

Signed-off-by: Babak K. Shandiz <babakks@github.com>

refactor(repo read): use FormatSize from internal/text

1fc783e

Signed-off-by: Babak K. Shandiz <babakks@github.com>

chore(repo read-file): remove unused fields and improve docs

07a0481

Signed-off-by: Babak K. Shandiz <babakks@github.com>

feat(repo): add read-dir command

3561f05

Signed-off-by: Babak K. Shandiz <babakks@github.com>

test(repo read-dir): add tests for read-dir

ed0caac

Signed-off-by: Babak K. Shandiz <babakks@github.com>

fix(repo read-dir): improve the error message for missing ref/path

3be9c74

Signed-off-by: Babak K. Shandiz <babakks@github.com>

test(repo read-dir): inline stub API responses

039d467

Signed-off-by: Babak K. Shandiz <babakks@github.com>

test(repo read-file): fix path mismatch on windows

9b503e7

Signed-off-by: Babak K. Shandiz <babakks@github.com>

test(acceptance/repo): add acceptance for read-file and read-dir comm…

855c217

…ands Signed-off-by: Babak K. Shandiz <babakks@github.com>

fix(repo read-file): hint at read-dir when appropriate

2564f12

Signed-off-by: Babak K. Shandiz <babakks@github.com>

babakks marked this pull request as ready for review June 3, 2026 22:29

babakks requested a review from a team as a code owner June 3, 2026 22:29

babakks requested review from BagToad and Copilot June 3, 2026 22:29

Copilot started reviewing on behalf of babakks June 3, 2026 22:29 View session

Copilot AI reviewed Jun 3, 2026

View reviewed changes

babakks and others added 2 commits June 16, 2026 15:02

Merge branch 'trunk' into babakks/feature-repo-read

f8dfbad

docs(skills/gh): document repo read-file and read-dir commands

fb3df6d

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

babakks and others added 5 commits June 16, 2026 15:20

docs(repo): add --json examples to read-file and read-dir

97c5cb2

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

docs(repo read-file): fix typo

298fd27

Signed-off-by: Babak K. Shandiz <babakks@github.com>

fix(repo read-file): propagate lstat error

30bba4f

Signed-off-by: Babak K. Shandiz <babakks@github.com>

fix(repo read-file): rename usafe flag to allow-escape-sequences

2334627

Signed-off-by: Babak K. Shandiz <babakks@github.com>

test(repo read-file): exercise ansi escape sequence check

8728b9c

Signed-off-by: Babak K. Shandiz <babakks@github.com>

niloytanvir566-code reviewed Jun 16, 2026

View reviewed changes

Comment thread internal/text/text_test.go

{1572864, "1.5 MB"},

{5242880, "5.0 MB"},

{1073741824, "1.0 GB"},

{1610612736, "1.5 GB"},

This comment was marked as spam.

Sign in to view

fix(internal/text): make FormatSize take int64 and clamp at largest unit

e10e3b2

Avoids an out-of-range panic for byte counts at or above one exabyte, which fit within int64, and lets the function accept the full int64 range. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

BagToad approved these changes Jun 17, 2026

View reviewed changes

Comment thread pkg/cmd/repo/read-file/read_file.go

Comment thread skills/gh/SKILL.md Outdated

Comment thread pkg/cmd/repo/read-file/read_file.go Outdated

Comment thread pkg/cmd/repo/read-file/read_file.go

Comment thread pkg/cmd/repo/read-file/read_file.go

docs(repo): polish read-file and read-dir docs

308135c

Signed-off-by: Babak K. Shandiz <babakks@github.com>

docs: improve skill around repo read-file

c2dae4f

Signed-off-by: Babak K. Shandiz <babakks@github.com>

BagToad merged commit 733e35c into trunk Jun 17, 2026
11 checks passed

BagToad deleted the babakks/feature-repo-read branch June 17, 2026 16:59

BrewTestBot mentioned this pull request Jun 17, 2026

gh 2.95.0 Homebrew/homebrew-core#288534

Merged

File	Description
pkg/cmd/repo/repo.go	Registers the new `read-file`/`read-dir` commands under `gh repo`.
pkg/cmd/repo/read-file/read_file.go	Implements command parsing and output modes for reading a single file.
pkg/cmd/repo/read-file/http.go	Adds REST Contents API fetching and decoding logic for `read-file`.
pkg/cmd/repo/read-file/read_file_test.go	Unit tests for `read-file` behaviors (TTY/non-TTY, JSON, output writing, etc.).
pkg/cmd/repo/read-dir/read_dir.go	Implements command parsing and output modes for listing a directory.
pkg/cmd/repo/read-dir/http.go	Adds GraphQL-backed directory listing and entry modeling for `read-dir`.
pkg/cmd/repo/read-dir/read_dir_test.go	Unit tests for `read-dir` behaviors (TTY/non-TTY, JSON, errors, etc.).
internal/text/text.go	Adds `FormatSize` helper for human-friendly byte formatting.
internal/text/text_test.go	Adds tests for `FormatSize`.
acceptance/testdata/repo/repo-read-file.txtar	Adds acceptance coverage for `repo read-file`.
acceptance/testdata/repo/repo-read-dir.txtar	Adds acceptance coverage for `repo read-dir`.

Sunbelt Computer Software

PL/B Language Development and Support

Uh oh!

Conversation

babakks commented Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

gh repo read-file

gh repo read-dir

Test plan

gh repo read-file

gh repo read-dir

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

babakks commented Jun 16, 2026

Uh oh!

This comment was marked as spam.

Uh oh!

BagToad left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

babakks commented Jun 3, 2026 •

edited

Loading

`gh repo read-file`

`gh repo read-dir`

`gh repo read-file`

`gh repo read-dir`