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);

Options

ref · string

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

ephemeral · boolean

When true, resolves the ref under the ephemeral namespace.

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

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 · string

Commit timestamp in RFC 3339 / ISO 8601 format.

commits[sha].message · string

Full commit message.

ref · string

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