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

# listCommits()

> List commit history with optional branch filtering.

<CodeGroup>
  ```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  // List commits from default branch
  const commits = await repo.listCommits();
  console.log(commits.commits[0]?.parentShas);

  // List commits from specific branch
  const branchCommits = await repo.listCommits({
    branch: 'feature/new-auth',
    limit: 20,
  });

  // List commits from an ephemeral branch
  const previewCommits = await repo.listCommits({
    branch: 'preview/pr-123',
    ephemeral: true,
  });

  const pathCommits = await repo.listCommits({
    branch: 'main',
    path: 'docs/guide.md',
  });
  ```

  ```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  commits = await repo.list_commits(
      branch="feature/new-auth",
      limit=20,
  )
  for commit in commits["commits"]:
      print(commit["sha"], commit["parent_shas"])

  # List commits from an ephemeral branch
  preview_commits = await repo.list_commits(
      branch="preview/pr-123",
      ephemeral=True,
  )

  path_commits = await repo.list_commits(
      branch="main",
      path="docs/guide.md",
  )
  ```

  ```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  // List commits from a branch
  commits, err := repo.ListCommits(context.Background(), storage.ListCommitsOptions{
  	Branch: "feature/new-auth",
  	Limit:  20,
  })
  for _, commit := range commits.Commits {
  	fmt.Println(commit.SHA, commit.ParentSHAs)
  }

  // List commits from an ephemeral branch
  ephemeral := true
  previewCommits, err := repo.ListCommits(context.Background(), storage.ListCommitsOptions{
  	Branch:    "preview/pr-123",
  	Ephemeral: &ephemeral,
  })

  pathCommits, err := repo.ListCommits(context.Background(), storage.ListCommitsOptions{
  	Branch: "main",
  	Path:   "docs/guide.md",
  })
  ```
</CodeGroup>

## Options

<ParamField path="branch" type="string">
  Branch name to list commits from. Defaults to the default branch.
</ParamField>

<ParamField path="limit" type="number">
  Maximum number of commits to return
</ParamField>

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

<ParamField path="ephemeral" type="boolean">
  Resolve `branch` against the ephemeral namespace instead of the persistent one (default: `false`)
</ParamField>

<ParamField path="path" type="string">
  Limit history to commits that touched a file or subtree.
</ParamField>

## Response

<ResponseField name="commits" type="array">
  List of commit objects.

  <Expandable title="commit fields">
    <ResponseField name="commits[].sha" type="string">
      Commit SHA. Go: `SHA`.
    </ResponseField>

    <ResponseField name="commits[].parentShas" type="string[]">
      Parent commit SHAs in Git parent order. Empty for root commits. Python: `parent_shas`; Go: `ParentSHAs`.
    </ResponseField>

    <ResponseField name="commits[].message" type="string">
      Commit message.
    </ResponseField>

    <ResponseField name="commits[].authorName" type="string">
      Author name. Python: `author_name`; Go: `AuthorName`.
    </ResponseField>

    <ResponseField name="commits[].authorEmail" type="string">
      Author email. Python: `author_email`; Go: `AuthorEmail`.
    </ResponseField>

    <ResponseField name="commits[].committerName" type="string">
      Committer name. Python: `committer_name`; Go: `CommitterName`.
    </ResponseField>

    <ResponseField name="commits[].committerEmail" type="string">
      Committer email. Python: `committer_email`; Go: `CommitterEmail`.
    </ResponseField>

    <ResponseField name="commits[].date" type="Date | datetime | time.Time">
      Parsed commit timestamp.
    </ResponseField>

    <ResponseField name="commits[].rawDate" type="string">
      RFC 3339 timestamp string as returned by the server. Python: `raw_date`; Go: `RawDate`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="nextCursor" type="string">
  Cursor for the next page (absent when no more results). Python: `next_cursor`; Go: `NextCursor`.
</ResponseField>

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