feat: add `repo read-file` and `repo read-dir` by babakks · Pull Request #13580 · cli/cli

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

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`.

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

+		Long: heredoc.Docf(`
+			Read the contents of a file in a GitHub repository without cloning it.
+
+			This command is in preview and and subject to change without notice.


+	if lr, err := lstatF(dest); err == nil {
+		if lr.isSymlink {
+			return "", fmt.Errorf("output path is a symlink")
+		}
+		if lr.isDir {
+			asDir = true
+		}
+	}


+	if lr, err := lstatF(dest); err == nil {
+		if lr.isSymlink {
+			return "", fmt.Errorf("output path is a symlink")
+		}
+		if !clobber {
+			return "", fmt.Errorf("output path already exists: %q (use --clobber to overwrite)", dest)
+		}
+	}


+	if content.Encoding == "base64" && content.Content != "" {
+		decoded, err := base64.StdEncoding.DecodeString(content.Content)
+		if err != nil {
+			return nil, fmt.Errorf("failed to decode base64 file content: %w", err)
+		}
+		file.Content = decoded
+	}


+	// Refuse terminal escape sequences unless --unsafe, in both TTY and non-TTY modes,
+	// so a malicious file cannot manipulate a downstream terminal.


+						NameRaw   string
+						PathRaw   string


+						Type      string
+						Mode      int
+						OID       string `graphql:"oid"`
+						Size      int


+// FormatSize formats a byte count using binary units (B, KB, MB, GB, TB, PB).
+// Values below a kilobyte are shown as whole bytes; larger values are shown with
+// one decimal place of precision.
+func FormatSize(n int) string {


+	units := []string{"KB", "MB", "GB", "TB", "PB"}
+	value := float64(n) / float64(div)
+	return fmt.Sprintf("%.1f %s", value, units[exp])


+	tests := []struct {
+		n    int
+		want string
+	}{
+		{0, "0 B"},
+		{1, "1 B"},
+		{512, "512 B"},
+		{1023, "1023 B"},
+		{1024, "1.0 KB"},
+		{1536, "1.5 KB"},
+		{2048, "2.0 KB"},
+		{10240, "10.0 KB"},
+		{524288, "512.0 KB"},
+		{1048576, "1.0 MB"},
+		{1572864, "1.5 MB"},
+		{5242880, "5.0 MB"},
+		{1073741824, "1.0 GB"},
+		{1610612736, "1.5 GB"},
+		{1099511627776, "1.0 TB"},
+		{1125899906842624, "1.0 PB"},


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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add `repo read-file` and `repo read-dir`#13580

feat: add `repo read-file` and `repo read-dir`#13580
babakks wants to merge 12 commits into
trunkfrom
babakks/feature-repo-read

babakks commented Jun 3, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		// Refuse terminal escape sequences unless --unsafe, in both TTY and non-TTY modes,
		// so a malicious file cannot manipulate a downstream terminal.

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

babakks commented Jun 3, 2026 •

edited

Loading

`gh repo read-file`

`gh repo read-dir`

`gh repo read-file`

`gh repo read-dir`