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

# listFiles()

> List all files in the repository at a specific ref.

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

  ```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  # List files from the default branch
  files = await repo.list_files(ref="main")
  print(files["paths"])  # List of file paths

  # List files from a specific branch or commit
  branch_files = await repo.list_files(ref="feature-branch")
  print(branch_files["paths"])

  # List files from the ephemeral namespace
  ephemeral_files = await repo.list_files(
      ref="feature/demo-work",
      ephemeral=True,
  )
  print(ephemeral_files["paths"])

  page = await repo.list_files(
      path="docs",
      recursive=False,
      limit=100,
  )
  print(page["entries"], page.get("next_cursor"))
  ```

  ```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  // List files from the default branch
  files, err := repo.ListFiles(context.Background(), storage.ListFilesOptions{
  	Ref: "main",
  })
  fmt.Println(files.Paths)

  ephemeral := true
  // List files from the ephemeral namespace
  ephemeralFiles, err := repo.ListFiles(context.Background(), storage.ListFilesOptions{
  	Ref:       "feature/demo-work",
  	Ephemeral: &ephemeral,
  })
  fmt.Println(ephemeralFiles.Paths)

  recursive := false
  page, err := repo.ListFiles(context.Background(), storage.ListFilesOptions{
  	Path:      "docs",
  	Recursive: &recursive,
  	Limit:     100,
  })
  fmt.Println(page.Entries, page.NextCursor)
  ```
</CodeGroup>

## Options

<ParamField path="ref" type="string">
  Branch name or commit SHA. Defaults to the default branch.
</ParamField>

<ParamField path="ephemeral" type="boolean">
  When `true`, resolves the ref under the ephemeral namespace.
</ParamField>

<ParamField path="path" type="string">
  Repository-relative file or subtree to list. An exact file path returns that file as a single
  `blob` entry.
</ParamField>

<ParamField path="recursive" type="boolean">
  For subtree paths, when `false`, returns direct children of `path`.
</ParamField>

<ParamField path="cursor" type="string">
  Pagination cursor from a previous response.
</ParamField>

<ParamField path="limit" type="number">
  Maximum entries to return.
</ParamField>

## Response

<ResponseField name="paths" type="array">
  List of file paths in the repository
</ResponseField>

<ResponseField name="ref" type="string">
  The resolved ref that was listed
</ResponseField>

<ResponseField name="entries" type="array">
  Structured tree entries returned with the listing.

  <Expandable title="entry fields">
    <ResponseField name="entries[].path" type="string">
      Entry path relative to the repository root.
    </ResponseField>

    <ResponseField name="entries[].type" type="string">
      Entry type: `blob`, `tree`, `symlink`, or `submodule`.
    </ResponseField>

    <ResponseField name="entries[].mode" type="string">
      Git file mode.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="nextCursor" type="string">
  Cursor for the next page. Python: `next_cursor`; Go: `NextCursor`.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  Whether additional pages are available. Python: `has_more`; Go: `HasMore`.
</ResponseField>