> ## Documentation Index
> Fetch the complete documentation index at: https://code.storage/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# repo.listFilesWithMetadata()

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

> [!WARNING]
>
> This page documents the earlier Code Storage SDKs: `@pierre/storage`, `pierre-storage`, and
> `code-storage-go`. New code uses the [Pierre SDK](https://code.storage/docs/sdks.md). To move code to the new SDK, use the
> [`pierre-migrate`
> skill](https://github.com/pierrecomputer/skills/tree/main/skills/pierre-migrate).

```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
// 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);
```

```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
# List files with metadata from the default branch
metadata = await repo.list_files_with_metadata()
print(metadata["files"][0]["last_commit_sha"])
print(metadata["commits"][metadata["files"][0]["last_commit_sha"]]["author"])

# List files with metadata from a specific branch or commit
branch_metadata = await repo.list_files_with_metadata(ref="feature-branch")
print(f"Files in {branch_metadata['ref']}:", len(branch_metadata["files"]))

# List files from the ephemeral namespace
ephemeral_metadata = await repo.list_files_with_metadata(
    ref="feature/demo-work",
    ephemeral=True,
)
print("Ephemeral files:", len(ephemeral_metadata["files"]))

page = await repo.list_files_with_metadata(
    path="src",
    limit=100,
)
print(page["files"][0].get("type"), page.get("next_cursor"))
```

```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
// List files with metadata from the default branch
metadata, err := repo.ListFilesWithMetadata(context.Background(), storage.ListFilesWithMetadataOptions{
	Ref: "main",
})
fmt.Println(metadata.Files[0].LastCommitSHA)
fmt.Println(metadata.Commits[metadata.Files[0].LastCommitSHA].Author)

ephemeral := true
// List files from the ephemeral namespace
ephemeralMetadata, err := repo.ListFilesWithMetadata(context.Background(), storage.ListFilesWithMetadataOptions{
	Ref:       "feature/demo-work",
	Ephemeral: &ephemeral,
})
fmt.Println("Ephemeral files:", len(ephemeralMetadata.Files))

page, err := repo.ListFilesWithMetadata(context.Background(), storage.ListFilesWithMetadataOptions{
	Path:  "src",
	Limit: 100,
})
fmt.Println(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.

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

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

The subject line of the commit message: the first paragraph of the message as one line,
without the body and the trailers. [`getCommit()`](https://code.storage/docs/sdk/repos/commit-get) returns the full
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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.