listFiles()

List all files in the repository at a specific ref.

TypeScript

// List files from default branch
const files = await repo.listFiles();
console.log(files.paths); // Array of file paths

// List files from specific branch or commit
const branchFiles = await repo.listFiles({
  ref: "feature-branch", // branch name or commit SHA
});
console.log(`Files in ${branchFiles.ref}:`, branchFiles.paths);

// List files from the ephemeral namespace
const ephemeralFiles = await repo.listFiles({
  ref: "feature/demo-work",
  ephemeral: true,
});
console.log(`Ephemeral files:`, ephemeralFiles.paths);

const page = await repo.listFiles({
  path: "docs",
  recursive: false,
  limit: 100,
});
console.log(page.entries, page.nextCursor);

Options

ref · string

Branch name or commit SHA. Defaults to the default branch.

ephemeral · boolean

When true, resolves the ref under the ephemeral namespace.

path · string

Repository-relative file or subtree to list. An exact file path returns that file as a single blob entry.

recursive · boolean

For subtree paths, when false, returns direct children of path.

cursor · string

Pagination cursor from a previous response.

limit · number

Maximum entries to return.

Response

paths · array

List of file paths in the repository

ref · string

The resolved ref that was listed

entries · array

Structured tree entries returned with the listing.

Show entry fields

entries[].path · string

Entry path relative to the repository root.

entries[].type · string

Entry type: blob, tree, symlink, or submodule.

entries[].mode · string

Git file mode.

nextCursor · string

Cursor for the next page. Python: next_cursor; Go: NextCursor.

hasMore · boolean

Whether additional pages are available. Python: has_more; Go: HasMore.