Searching refs
Prefix-match branches, tags, and commit SHAs with refs.search — built for autocompletion.
refs.search matches a query against a repository’s branch names, tag names, and — when the input looks
like a SHA — its commits, returning one merged suggestion list. It’s designed for ref pickers and
autocompletion inputs: one call per keystroke, server-side filtering on every provider.
Searching
const matches = await client.refs.search({
repo: 'capawesome-team/repo-sdk',
query: 'feat',
});
// [
// { type: 'branch', name: 'feature/login', sha: '4f2a…', raw: {…} },
// { type: 'branch', name: 'feature/logout', sha: '9c81…', raw: {…} },
// { type: 'tag', name: 'feat-preview', sha: 'd0be…', raw: {…} },
// ]Matching is by prefix on the ref name. Results are ordered branches → tags → commit, truncated to
limit (default 20). Requires the refSearch capability — all current providers support it, but gate
on client.capabilities.refSearch if you accept arbitrary providers.
Parameters
repo?string
The repository to search in.
stringquery?string
The prefix to match ref names against. An empty string returns the first branches and tags unfiltered.
stringtypes?RefType[]
Which ref types to match: 'branch', 'tag', 'commit'. Defaults to all three.
RefType[]limit?number
Maximum number of results (default 20).
numberThe RefMatch result
type?'branch' | 'tag' | 'commit'
What kind of ref matched.
'branch' | 'tag' | 'commit'name?string
The ref name without its refs/heads/ or refs/tags/ prefix; the full SHA for commit matches.
stringref?string
The fully-qualified form: refs/heads/<name> for branches, refs/tags/<name> for tags, the SHA itself for commit matches. Always accepted back by refs.resolve.
stringsha?string
The SHA the ref points to. In search results on GitHub and Gitea, annotated tags carry the tag object SHA, not the peeled commit — use refs.resolve or tags.get when you need the commit.
stringraw?unknown
The untouched provider payload.
unknownCommit SHA input
When query is 4–40 hex characters and types includes 'commit', the SDK additionally tries to
resolve it as a (possibly abbreviated) commit SHA via the provider. A resolved commit is appended as a
type: 'commit' match; an unresolvable SHA is simply omitted — other errors (auth, rate limits)
propagate as usual.
await client.refs.search({ repo: 'o/r', query: 'a1b2c3d' });
// [ …matching branches/tags…, { type: 'commit', name: 'a1b2c3d4…', ref: 'a1b2c3d4…', sha: 'a1b2c3d4…', raw: {…} } ]Empty input
An empty query is served from the paginated branch and tag list endpoints instead of the search
endpoints, so it stays cheap on every provider — useful for showing initial suggestions before the user
types. Pin repos.get(...).defaultBranch to the top of that list for a typical ref picker.