Skip to main content
The RefService provides RPCs for working with Git references (refs). This includes operations on branches, tags, and other references like finding, listing, creating, deleting, and querying reference information.

​
FindDefaultBranchName

Finds the name of the default branch (typically “main” or “master”).

​
Request

​
repository
Repository
required
The repository to query

​
Response

​
name
bytes
The name of the default branch (without “refs/heads/” prefix)

​
Example

{
  "repository": {
    "storage_name": "default",
    "relative_path": "@hashed/ab/cd/abcd1234.git"
  }
}

​
FindBranch

Finds a branch by its unqualified name and returns the commit it points to.

​
Request

​
repository
Repository
required
The repository to search in
​
name
bytes
required
Branch name only (without “refs/heads/” prefix)

​
Response

​
branch
Branch
The branch object, or null if not found

​
Example

{
  "repository": {
    "storage_name": "default",
    "relative_path": "@hashed/ab/cd/abcd1234.git"
  },
  "name": "main"
}

​
FindAllBranchNames

Returns all branch names in the repository.

​
Request

​
repository
Repository
required
The repository to list branches from

​
Response (Stream)

​
names
bytes[]
Array of branch names

​
FindLocalBranches

Finds all local branches with detailed information.

​
Request

​
repository
Repository
required
The repository to list branches from
​
sort_by
SortBy
Sort order: NAME, UPDATED_ASC, or UPDATED_DESC
​
pagination_params
PaginationParameter
Pagination configuration. The page token is the branch name with “refs/heads/” prefix.

​
Response (Stream)

​
branches
FindLocalBranchResponse[]
Array of local branches
​
branches[].name
bytes
Branch name
​
branches[].commit_id
string
Commit ID the branch points to
​
branches[].commit_subject
bytes
Subject line of the commit
​
branches[].commit_author
FindLocalBranchCommitAuthor
Author of the commit
​
branches[].commit_committer
FindLocalBranchCommitAuthor
Committer of the commit
​
branches[].commit
GitCommit
Full commit object

​
Example

{
  "repository": {
    "storage_name": "default",
    "relative_path": "@hashed/ab/cd/abcd1234.git"
  },
  "sort_by": "UPDATED_DESC",
  "pagination_params": {
    "limit": 50
  }
}

​
FindAllBranches

Finds all branches, optionally filtered to only merged branches.

​
Request

​
repository
Repository
required
The repository to list branches from
​
merged_only
bool
Only return branches merged into the root ref
​
merged_branches
bytes[]
If merged_only is true, this is the list of branches to check

​
Response (Stream)

​
branches
Branch[]
Array of branches
​
branches[].name
bytes
Branch name
​
branches[].target
GitCommit
Commit the branch points to

​
FindTag

Finds a specific tag by name.

​
Request

​
repository
Repository
required
The repository to search in
​
tag_name
bytes
required
Name of the tag to find

​
Response

​
tag
Tag
The tag object, or null if not found

​
Example

{
  "repository": {
    "storage_name": "default",
    "relative_path": "@hashed/ab/cd/abcd1234.git"
  },
  "tag_name": "v1.0.0"
}

​
FindAllTagNames

Returns all tag names in the repository.

​
Request

​
repository
Repository
required
The repository to list tags from

​
Response (Stream)

​
names
bytes[]
Array of tag names

​
FindAllTags

Returns all tags in the repository with full tag objects.

​
Request

​
repository
Repository
required
The repository to list tags from
​
sort_by
SortBy
Sort configuration with key (REFNAME or CREATORDATE) and direction
​
pagination_params
PaginationParameter
Pagination configuration. The page token is the tag name with “refs/tags/” prefix.

​
Response (Stream)

​
tags
Tag[]
Array of tags

​
Example

{
  "repository": {
    "storage_name": "default",
    "relative_path": "@hashed/ab/cd/abcd1234.git"
  },
  "sort_by": {
    "key": "CREATORDATE",
    "direction": "DESCENDING"
  },
  "pagination_params": {
    "limit": 100
  }
}

​
FindAllRemoteBranches

Finds all branches from a specific remote.

​
Request

​
repository
Repository
required
The repository to search in
​
remote_name
string
required
Name of the remote

​
Response (Stream)

​
branches
Branch[]
Array of remote branches

​
RefExists

Checks if a reference exists.

​
Request

​
repository
Repository
required
The repository to check in
​
ref
bytes
required
Fully qualified reference name (must start with “refs/“)

​
Response

​
value
bool
True if the reference exists

​
Example

{
  "repository": {
    "storage_name": "default",
    "relative_path": "@hashed/ab/cd/abcd1234.git"
  },
  "ref": "refs/heads/feature-branch"
}

​
ListRefs

Lists all references matching given patterns. Symbolic references are resolved to the object ID they point at.

​
Request

​
repository
Repository
required
The repository to list refs from
​
patterns
bytes[]
required
Patterns in the format accepted by git-for-each-ref(1). At least one pattern must be given. Non-matching patterns are silently ignored.
​
head
bool
Whether to include the HEAD reference. By default, pseudo-refs are not included.
​
sort_by
SortBy
Sort configuration with key (REFNAME, CREATORDATE, AUTHORDATE, or COMMITTERDATE) and direction

​
Response (Stream)

​
references
Reference[]
Array of references found
​
references[].name
bytes
Fully qualified name of the reference
​
references[].target
string
Object ID the reference points to

​
Example

{
  "repository": {
    "storage_name": "default",
    "relative_path": "@hashed/ab/cd/abcd1234.git"
  },
  "patterns": ["refs/heads/*", "refs/tags/*"],
  "head": true
}

​
FindRefsByOID

Finds all fully qualified reference names that point to a specific object ID.

​
Request

​
repository
Repository
required
The repository to search in
​
oid
string
required
Object ID to find references for (can be a prefix)
​
ref_patterns
string[]
Patterns to filter references. Can be branch names, tag names, or fully qualified ref names. If empty, defaults to “refs/heads/” and “refs/tags/”.
​
sort_field
string
Sort field for results. If empty, defaults to “refname” (lexicographic order).
​
limit
uint32
Maximum number of results. 0 means no limit.

​
Response

​
refs
string[]
Array of fully-qualified reference names

​
Example

{
  "repository": {
    "storage_name": "default",
    "relative_path": "@hashed/ab/cd/abcd1234.git"
  },
  "oid": "abc123def456",
  "ref_patterns": ["refs/heads/*"],
  "limit": 10
}

​
DeleteRefs

Deletes multiple references.

​
Request

​
repository
Repository
required
The repository to delete refs from
​
except_with_prefix
bytes[]
Delete all refs except those with these prefixes (mutually exclusive with refs)
​
refs
bytes[]
Specific refs to delete (mutually exclusive with except_with_prefix)

​
Response

​
git_error
string
Error message if the operation failed, empty on success
This is a destructive operation. Use with caution.

​
ListBranchNamesContainingCommit

Lists all branch names that contain a specific commit.

​
Request

​
repository
Repository
required
The repository to search in
​
commit_id
string
required
The commit ID to search for
​
limit
uint32
Maximum number of branch names to return. 0 means return all.

​
Response (Stream)

​
branch_names
bytes[]
Array of branch names containing the commit

​
Example

{
  "repository": {
    "storage_name": "default",
    "relative_path": "@hashed/ab/cd/abcd1234.git"
  },
  "commit_id": "abc123def456...",
  "limit": 50
}

​
ListTagNamesContainingCommit

Lists all tag names that contain a specific commit.

​
Request

​
repository
Repository
required
The repository to search in
​
commit_id
string
required
The commit ID to search for
​
limit
uint32
Maximum number of tag names to return. 0 means return all.

​
Response (Stream)

​
tag_names
bytes[]
Array of tag names containing the commit

​
GetTagSignatures

Retrieves signatures for annotated tags. Revisions which don’t resolve to an annotated tag are silently discarded. Tags which are annotated but not signed will return a response with no signature, but unsigned contents will still be returned.

​
Request

​
repository
Repository
required
The repository to retrieve tag signatures from
​
tag_revisions
string[]
required
Set of revisions to look up. Supports syntax as specified by gitrevisions(7). All revisions are expected to resolve to annotated tag objects. At least one revision must be provided.

​
Response (Stream)

​
signatures
TagSignature[]
Array of tag signatures found
​
signatures[].tag_id
string
Resolved object ID of the tag
​
signatures[].signature
bytes
Cryptographic signature of the tag. Unset if the tag is not signed.
​
signatures[].content
bytes
Contents which are signed by the signature. Includes both message and metadata.

​
Example

{
  "repository": {
    "storage_name": "default",
    "relative_path": "@hashed/ab/cd/abcd1234.git"
  },
  "tag_revisions": ["v1.0.0", "v1.1.0"]
}

​
GetTagMessages

Retrieves messages from annotated tags.

​
Request

​
repository
Repository
required
The repository to retrieve tag messages from
​
tag_ids
string[]
required
Array of tag IDs

​
Response (Stream)

​
tag_id
string
The tag ID. Only present for a new tag message.
​
message
bytes
The tag message

Build docs developers (and LLMs) love

Get started for freeTalk to us