listFilesWithMetadata()

List all files in the repository at a specific ref, with per-file git metadata.

TypeScript

// List files with metadata from the default branch
const metadata = await repo.listFilesWithMetadata();
console.log(metadata.files[0].lastCommitSha);
console.log(metadata.commits[metadata.files[0].lastCommitSha].author);

// List files with metadata from a specific branch or commit
const branchMetadata = await repo.listFilesWithMetadata({
  ref: "feature-branch", // branch name or commit SHA
});
console.log(`Files in ${branchMetadata.ref}:`, branchMetadata.files.length);

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

const page = await repo.listFilesWithMetadata({
  path: "src",
  limit: 100,
});
console.log(page.files[0].type, 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 one metadata entry.

recursive · boolean

Accepted for symmetry with listFiles; metadata listings are always recursive.

cursor · string

Pagination cursor from a previous response.

limit · number

Maximum files to return.

ttl · number

Time-to-live in seconds for the JWT used in the request.

Response

files · array

One entry per file in the tree at the resolved ref.

Show file fields

files[].path · string

File path relative to the repository root.

files[].mode · string

Git file mode (e.g. 100644 for a regular file, 100755 for executable).

files[].size · number

File size in bytes.

files[].lastCommitSha · string

SHA of the most recent commit that modified this file. Use this key to look up the corresponding entry in commits. Python: last_commit_sha — Go: LastCommitSHA

files[].type · string

Entry type when returned by the API: blob, tree, symlink, or submodule.

commits · object

A map of commit SHA → commit metadata. Each SHA referenced by files[].lastCommitSha has exactly one entry here. The map is deduplicated — if many files share the same last-touching commit, that commit appears once.

Show commit fields

commits[sha].author · string

Commit author name.

commits[sha].date · Date | datetime | time.Time

Parsed commit timestamp.

commits[sha].rawDate · string

RFC 3339 timestamp string as returned by the server. Python: raw_date; Go: RawDate.

commits[sha].message · string

Full commit message.

ref · string

The ref the server resolved and used, regardless of what was passed in options.

nextCursor · string

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

hasMore · boolean

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