Working with commits

List commits on a ref and resolve a ref to a single commit.

commits.list / commits.listAll page through a repository’s history with optional ref, since, until, path, and author filters, while commits.get resolves a branch, tag, or SHA to one normalized Commit.

Listing commits

commits.list returns one Page<Commit>; commits.listAll follows cursors and yields every commit. Both require a repo and accept optional filters:

const { data: commits, cursor } = await client.commits.list({
  repo: 'capawesome-team/repo-sdk',
  ref: 'main',
  since: new Date('2024-01-01'),
  limit: 20,
});

if (cursor) {
  const next = await client.commits.list({
    repo: 'capawesome-team/repo-sdk',
    ref: 'main',
    cursor,
  });
}

Or iterate the whole history lazily and break when you’ve seen enough:

for await (const commit of client.commits.listAll({ repo: 'capawesome-team/repo-sdk', ref: 'main' })) {
  console.log(commit.sha, commit.message);
}

Resolving a ref to one commit

commits.get resolves a branch, tag, or full SHA to a single normalized Commit:

const head = await client.commits.get({ repo: 'capawesome-team/repo-sdk', ref: 'main' });
console.log(head.sha, head.message);

await client.commits.get({ repo: 'capawesome-team/repo-sdk', ref: 'v1.0.0' }); // tag
await client.commits.get({ repo: 'capawesome-team/repo-sdk', ref: 'a1b2c3d…' }); // SHA

When the ref is an annotated tag, it is dereferenced to the commit it points at, so sha is always a commit SHA. A ref that doesn’t exist throws a RepoError with code: 'not_found'.

The normalized Commit

A GitActor is { name: string; email?: string; date: Date; user?: UserRef }. When the provider can resolve the actor to an account — GitHub, Bitbucket, and Gitea can; GitLab and Azure DevOps never return account data for commits — user carries { id, username, avatarUrl? }. Check the commitUserRef capability to know whether a provider can ever populate it; even on capable providers it is undefined for unmapped actors (e.g. an email not linked to any account).

Building a commit web URL without a request

Commit.url comes from the provider’s API response, so it is only available after fetching the commit. When you already hold a repository web URL and a SHA — for example from a webhook delivery — each provider subpath exports a pure commitWebUrl helper that builds the URL locally:

import { commitWebUrl } from 'repo-sdk/github';

commitWebUrl('https://github.com/capawesome-team/repo-sdk', 'abc123');
// https://github.com/capawesome-team/repo-sdk/commit/abc123

The first argument composes with the normalized Repository.urls.web. Each provider applies its own path convention (/commit/ on GitHub, Azure DevOps, and Gitea, /commits/ on Bitbucket, /-/commit/ on GitLab), so import the helper from the matching provider subpath.