pub struct RepositoriesClient { /* private fields */ }Expand description
Domain client for repository, branch, tag, git-ref, and commit operations.
Obtained via InstallationClient::repositories(). Cheap to clone (Arc-backed).
See docs/specs/interfaces/repository-operations.md
Implementations§
Source§impl RepositoriesClient
impl RepositoriesClient
Sourcepub async fn get_commit(
&self,
owner: &str,
repo: &str,
ref_name: &str,
) -> Result<FullCommit, ApiError>
pub async fn get_commit( &self, owner: &str, repo: &str, ref_name: &str, ) -> Result<FullCommit, ApiError>
Get a single commit by SHA, branch name, or tag name.
Retrieves complete commit details including the author, committer, commit message, parent references, and GPG verification status.
§Arguments
owner- Repository owner loginrepo- Repository nameref_name- Commit SHA (full or abbreviated), branch name, or tag name
§Returns
Returns a FullCommit with complete metadata.
§Errors
ApiError::NotFound- Commit or ref doesn’t exist, or repository not foundApiError::InvalidRequest- Invalid ref syntax or empty repository (GitHub returns 422)ApiError::AuthorizationFailed- Missingcontents:readpermissionApiError::AuthenticationFailed- Token expired or invalidApiError::HttpError- Unexpected API response
§Examples
// Get by SHA
let commit = client.get_commit("owner", "repo", "abc123def456").await?;
println!("Message: {}", commit.commit.message);
// Get by branch name
let head = client.get_commit("owner", "repo", "main").await?;
println!("HEAD: {}", head.sha);
// Get by tag
let release = client.get_commit("owner", "repo", "v1.0.0").await?;
println!("Release commit: {}", release.sha);§GitHub API
GET /repos/{owner}/{repo}/commits/{ref}
See https://docs.github.com/en/rest/commits/commits#get-a-commit
Sourcepub async fn list_commits(
&self,
owner: &str,
repo: &str,
sha: Option<&str>,
path: Option<&str>,
author: Option<&str>,
since: Option<DateTime<Utc>>,
until: Option<DateTime<Utc>>,
per_page: Option<u32>,
page: Option<u32>,
) -> Result<Vec<FullCommit>, ApiError>
pub async fn list_commits( &self, owner: &str, repo: &str, sha: Option<&str>, path: Option<&str>, author: Option<&str>, since: Option<DateTime<Utc>>, until: Option<DateTime<Utc>>, per_page: Option<u32>, page: Option<u32>, ) -> Result<Vec<FullCommit>, ApiError>
List commits in a repository with optional filtering.
Returns commits in reverse chronological order (newest first). All filter arguments are combined with AND logic.
§Arguments
owner- Repository owner loginrepo- Repository namesha- SHA or branch name to start listing from (default: repository default branch)path- Only return commits that modified this file path or directoryauthor- Filter by GitHub username or commit author email addresssince- Only include commits after this timestamp (inclusive)until- Only include commits before this timestamp (inclusive)per_page- Number of results per page; clamped to the range 1..=100page- Page number for pagination (1-based, default: 1)
§Returns
Returns a Vec<FullCommit> in reverse chronological order.
§Errors
ApiError::NotFound- Repository not foundApiError::InvalidRequest- Repository is empty (GitHub returns 422)ApiError::AuthorizationFailed- Missingcontents:readpermissionApiError::AuthenticationFailed- Token expired or invalidApiError::HttpError- Unexpected API response
§Examples
// List recent commits on the default branch
let commits = client.list_commits(
"owner", "repo",
None, None, None, None, None, None, None
).await?;
// List commits on a feature branch
let feature_commits = client.list_commits(
"owner", "repo",
Some("feature-branch"), None, None, None, None, None, None
).await?;
// List commits affecting a specific file
let readme_commits = client.list_commits(
"owner", "repo",
None, Some("README.md"), None, None, None, Some(50), None
).await?;
// List commits by author in a date range
let since = "2026-01-01T00:00:00Z".parse::<DateTime<Utc>>()?;
let until = "2026-01-31T23:59:59Z".parse::<DateTime<Utc>>()?;
let author_commits = client.list_commits(
"owner", "repo",
None, None, Some("alice"), Some(since), Some(until), None, None
).await?;§Notes
per_pageis silently clamped to the range 1..=100 (GitHub API maximum is 100; 0 is raised to 1).- Empty repositories cause GitHub to return 422, mapped to
ApiError::InvalidRequest.
§GitHub API
GET /repos/{owner}/{repo}/commits
See https://docs.github.com/en/rest/commits/commits#list-commits
Sourcepub async fn compare(
&self,
owner: &str,
repo: &str,
base: &str,
head: &str,
) -> Result<Comparison, ApiError>
pub async fn compare( &self, owner: &str, repo: &str, base: &str, head: &str, ) -> Result<Comparison, ApiError>
Compare two commits, branches, or tags.
Returns a complete comparison including the list of commits between the two refs and every file that changed, with per-file statistics. Useful for changelog generation and release notes automation.
§Arguments
owner- Repository owner loginrepo- Repository namebase- Base ref (SHA, branch, or tag) — the starting pointhead- Head ref (SHA, branch, or tag) — the ending point
§Returns
Returns a Comparison with commits, file changes, and statistics.
§Errors
ApiError::NotFound- Base or head ref not found, or repository not foundApiError::AuthorizationFailed- Missingcontents:readpermissionApiError::AuthenticationFailed- Token expired or invalidApiError::HttpError- Unexpected API response
§Examples
// Compare two tags for release notes
let cmp = client.compare("owner", "repo", "v1.0.0", "v1.1.0").await?;
println!("Status: {}", cmp.status);
println!("Commits: {}", cmp.total_commits);
println!("Files changed: {}", cmp.files.len());
for commit in &cmp.commits {
let subject = commit.commit.message.lines().next().unwrap_or("");
println!("- {}", subject);
}
// Compare a feature branch to main
let branch_diff = client.compare("owner", "repo", "main", "feature-x").await?;
match branch_diff.status.as_str() {
"ahead" => println!("Feature is {} commits ahead", branch_diff.ahead_by),
"behind" => println!("Feature is {} commits behind", branch_diff.behind_by),
"identical" => println!("Branches are identical"),
"diverged" => println!("Branches have diverged"),
_ => {}
}§Comparison Status Values
| Status | Meaning |
|---|---|
"ahead" | Head has commits not in base |
"behind" | Base has commits not in head |
"identical" | Both refs point to the same commit |
"diverged" | Refs have different histories |
§Notes
- Commits are returned in chronological order (oldest to newest).
- GitHub limits comparisons to 250 commits.
- File patches may be absent for binary files or very large diffs.
§GitHub API
GET /repos/{owner}/{repo}/compare/{base}...{head}
See https://docs.github.com/en/rest/commits/commits#compare-two-commits
Source§impl RepositoriesClient
impl RepositoriesClient
Sourcepub async fn get(&self, owner: &str, repo: &str) -> Result<Repository, ApiError>
pub async fn get(&self, owner: &str, repo: &str) -> Result<Repository, ApiError>
Get repository metadata.
Retrieves complete metadata for a repository including owner information, visibility settings, default branch, and timestamps.
§Arguments
owner- Repository owner (username or organization)repo- Repository name
§Returns
Returns Repository with complete metadata on success.
§Errors
ApiError::NotFound- Repository does not exist or is not accessibleApiError::AuthorizationFailed- Insufficient permissions to access repositoryApiError::HttpError- GitHub API returned an error
§Example
let repo = client.get("octocat", "Hello-World").await?;
println!("Repository: {}", repo.full_name);
println!("Default branch: {}", repo.default_branch);Sourcepub async fn list_branches(
&self,
owner: &str,
repo: &str,
) -> Result<Vec<Branch>, ApiError>
pub async fn list_branches( &self, owner: &str, repo: &str, ) -> Result<Vec<Branch>, ApiError>
List all branches in a repository.
Returns an array of all branches with their commit information and protection status.
§Arguments
owner- Repository ownerrepo- Repository name
§Returns
Returns Vec<Branch> with all repository branches.
§Errors
ApiError::NotFound- Repository does not existApiError::AuthorizationFailed- Insufficient permissions
§Example
let branches = client.list_branches("octocat", "Hello-World").await?;
for branch in branches {
println!("Branch: {} (protected: {})", branch.name, branch.protected);
}Sourcepub async fn get_branch(
&self,
owner: &str,
repo: &str,
branch: &str,
) -> Result<Branch, ApiError>
pub async fn get_branch( &self, owner: &str, repo: &str, branch: &str, ) -> Result<Branch, ApiError>
Get a specific branch by name.
Retrieves detailed information about a single branch including commit SHA and protection status.
§Arguments
owner- Repository ownerrepo- Repository namebranch- Branch name
§Returns
Returns Branch with branch details.
§Errors
ApiError::NotFound- Branch or repository does not existApiError::AuthorizationFailed- Insufficient permissions
§Example
let branch = client.get_branch("octocat", "Hello-World", "main").await?;
println!("Branch {} at commit {}", branch.name, branch.commit.sha);Sourcepub async fn get_ref(
&self,
owner: &str,
repo: &str,
ref_name: &str,
) -> Result<GitRef, ApiError>
pub async fn get_ref( &self, owner: &str, repo: &str, ref_name: &str, ) -> Result<GitRef, ApiError>
Get a Git reference (branch or tag).
Retrieves information about a Git reference including the SHA it points to.
§Arguments
owner- Repository ownerrepo- Repository nameref_name- Reference name (e.g., “heads/main” or “tags/v1.0.0”)
§Returns
Returns GitRef with reference details.
§Errors
ApiError::NotFound- Reference does not exist
§Example
let git_ref = client.get_ref("octocat", "Hello-World", "heads/main").await?;
println!("Ref {} points to {}", git_ref.ref_name, git_ref.object.sha);Sourcepub async fn create_ref(
&self,
owner: &str,
repo: &str,
ref_name: &str,
sha: &str,
) -> Result<GitRef, ApiError>
pub async fn create_ref( &self, owner: &str, repo: &str, ref_name: &str, sha: &str, ) -> Result<GitRef, ApiError>
Create a new Git reference (branch or tag).
Creates a new reference pointing to the specified SHA.
§Arguments
owner- Repository ownerrepo- Repository nameref_name- Full reference name (e.g., “refs/heads/new-branch”)sha- SHA that the reference should point to
§Returns
Returns GitRef for the newly created reference.
§Errors
ApiError::InvalidRequest- Reference already exists or invalid SHA
§Example
let git_ref = client.create_ref(
"octocat",
"Hello-World",
"refs/heads/new-feature",
"aa218f56b14c9653891f9e74264a383fa43fefbd"
).await?;Sourcepub async fn update_ref(
&self,
owner: &str,
repo: &str,
ref_name: &str,
sha: &str,
force: bool,
) -> Result<GitRef, ApiError>
pub async fn update_ref( &self, owner: &str, repo: &str, ref_name: &str, sha: &str, force: bool, ) -> Result<GitRef, ApiError>
Update an existing Git reference.
Updates a reference to point to a new SHA. Use force=true to allow
non-fast-forward updates.
§Arguments
owner- Repository ownerrepo- Repository nameref_name- Reference name (e.g., “heads/main”)sha- New SHA for the referenceforce- Allow non-fast-forward updates
§Returns
Returns GitRef with updated reference details.
§Errors
ApiError::NotFound- Reference does not existApiError::InvalidRequest- Invalid SHA or non-fast-forward without force
§Example
let git_ref = client.update_ref(
"octocat",
"Hello-World",
"heads/feature",
"bb218f56b14c9653891f9e74264a383fa43fefbd",
false
).await?;Sourcepub async fn delete_ref(
&self,
owner: &str,
repo: &str,
ref_name: &str,
) -> Result<(), ApiError>
pub async fn delete_ref( &self, owner: &str, repo: &str, ref_name: &str, ) -> Result<(), ApiError>
Delete a Git reference.
Permanently deletes a Git reference. Use with caution as this operation cannot be undone.
§Arguments
owner- Repository ownerrepo- Repository nameref_name- Reference name (e.g., “heads/old-feature”)
§Errors
ApiError::NotFound- Reference does not exist
§Example
client.delete_ref("octocat", "Hello-World", "heads/old-feature").await?;List all tags in a repository.
Returns an array of all tags with their associated commit information.
§Arguments
owner- Repository ownerrepo- Repository name
§Returns
Returns Vec<Tag> with all repository tags. Returns empty vector if no tags exist.
§Errors
ApiError::NotFound- Repository does not existApiError::AuthorizationFailed- Insufficient permissions
§Example
let tags = client.list_tags("octocat", "Hello-World").await?;
for tag in tags {
println!("Tag: {} at {}", tag.name, tag.commit.sha);
}Sourcepub async fn create_branch(
&self,
owner: &str,
repo: &str,
branch_name: &str,
from_sha: &str,
) -> Result<GitRef, ApiError>
pub async fn create_branch( &self, owner: &str, repo: &str, branch_name: &str, from_sha: &str, ) -> Result<GitRef, ApiError>
Create a new branch (convenience wrapper around create_git_ref).
Creates a new branch reference pointing to the specified commit. This is a convenience method that automatically adds the “refs/heads/” prefix.
§Arguments
owner- Repository ownerrepo- Repository namebranch_name- Branch name (without “refs/heads/” prefix)from_sha- SHA of the commit to branch from
§Returns
Returns GitRef for the newly created branch.
§Errors
ApiError::InvalidRequest- Branch already exists or invalid SHA
§Example
let branch = client.create_branch(
"octocat",
"Hello-World",
"new-feature",
"aa218f56b14c9653891f9e74264a383fa43fefbd"
).await?;
println!("Created branch: {}", branch.ref_name);Sourcepub async fn create_tag(
&self,
owner: &str,
repo: &str,
tag_name: &str,
from_sha: &str,
) -> Result<GitRef, ApiError>
pub async fn create_tag( &self, owner: &str, repo: &str, tag_name: &str, from_sha: &str, ) -> Result<GitRef, ApiError>
Create a new tag (convenience wrapper around create_git_ref).
Creates a new tag reference pointing to the specified commit. This is a convenience method that automatically adds the “refs/tags/” prefix.
§Arguments
owner- Repository ownerrepo- Repository nametag_name- Tag name (without “refs/tags/” prefix)from_sha- SHA of the commit to tag
§Returns
Returns GitRef for the newly created tag.
§Errors
ApiError::InvalidRequest- Tag already exists or invalid SHA
§Example
let tag = client.create_tag(
"octocat",
"Hello-World",
"v1.0.0",
"aa218f56b14c9653891f9e74264a383fa43fefbd"
).await?;
println!("Created tag: {}", tag.ref_name);Trait Implementations§
Source§impl Clone for RepositoriesClient
impl Clone for RepositoriesClient
Source§fn clone(&self) -> RepositoriesClient
fn clone(&self) -> RepositoriesClient
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more