Skip to content

docs: Extend the description of ref parameters #3643

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 24, 2025
Merged

docs: Extend the description of ref parameters #3643

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions example/commitpr/main.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ var ctx = context.Background()
// getRef returns the commit branch reference object if it exists or creates it
// from the base branch before returning it.
func getRef() (ref *github.Reference, err error) {
if ref, _, err = client.Git.GetRef(ctx, *sourceOwner, *sourceRepo, "refs/heads/"+*commitBranch); err == nil {
if ref, _, err = client.Git.GetRef(ctx, *sourceOwner, *sourceRepo, branchRef(*commitBranch)); err == nil {
return ref, nil
}

Expand All @@ -78,14 +78,19 @@ func getRef() (ref *github.Reference, err error) {
}

var baseRef *github.Reference
if baseRef, _, err = client.Git.GetRef(ctx, *sourceOwner, *sourceRepo, "refs/heads/"+*baseBranch); err != nil {
if baseRef, _, err = client.Git.GetRef(ctx, *sourceOwner, *sourceRepo, branchRef(*baseBranch)); err != nil {
return nil, err
}
newRef := &github.Reference{Ref: github.Ptr("refs/heads/" + *commitBranch), Object: &github.GitObject{SHA: baseRef.Object.SHA}}
newRef := &github.Reference{Ref: github.Ptr(branchRef(*commitBranch)), Object: &github.GitObject{SHA: baseRef.Object.SHA}}
ref, _, err = client.Git.CreateRef(ctx, *sourceOwner, *sourceRepo, newRef)
return ref, err
}

// branchRef generates the fully qualified git reference for the given branch name.
func branchRef(name string) string {
return "refs/heads/" + name
}

// getTree generates the tree to commit based on the given files and the commit
// of the ref you got in getRef.
func getTree(ref *github.Reference) (tree *github.Tree, err error) {
Expand Down
4 changes: 4 additions & 0 deletions github/checks.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -269,6 +269,8 @@ type ListCheckRunsResults struct {
}

// ListCheckRunsForRef lists check runs for a specific ref.
// The ref can be a commit SHA, branch name `heads/<branch name>`, or tag name `tags/<tag name>`.
// For more information, see "Git References" in the Git documentation https://git-scm.com/book/en/v2/Git-Internals-Git-References.
//
// GitHub API docs: https://docs.github.com/rest/checks/runs#list-check-runs-for-a-git-reference
//
Expand Down Expand Up @@ -357,6 +359,8 @@ type ListCheckSuiteResults struct {
}

// ListCheckSuitesForRef lists check suite for a specific ref.
// The ref can be a commit SHA, branch name `heads/<branch name>`, or tag name `tags/<tag name>`.
// For more information, see "Git References" in the Git documentation https://git-scm.com/book/en/v2/Git-Internals-Git-References.
//
// GitHub API docs: https://docs.github.com/rest/checks/suites#list-check-suites-for-a-git-reference
//
Expand Down
3 changes: 3 additions & 0 deletions github/git_refs.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ import (

// Reference represents a GitHub reference.
type Reference struct {
// The name of the fully qualified reference, i.e.: `refs/heads/master`.
Ref *string `json:"ref"`
URL *string `json:"url"`
Object *GitObject `json:"object"`
Expand Down Expand Up @@ -48,6 +49,7 @@ type updateRefRequest struct {
}

// GetRef fetches a single reference in a repository.
// The ref must be formatted as `heads/<branch name>` for branches and `tags/<tag name>` for tags.
//
// GitHub API docs: https://docs.github.com/rest/git/refs#get-a-reference
//
Expand Down Expand Up @@ -82,6 +84,7 @@ func refURLEscape(ref string) string {
// ReferenceListOptions specifies optional parameters to the
// GitService.ListMatchingRefs method.
type ReferenceListOptions struct {
// The ref must be formatted as `heads/<branch name>` for branches and `tags/<tag name>` for tags.
Ref string `url:"-"`

ListOptions
Expand Down
2 changes: 1 addition & 1 deletion github/repos_deployments.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ type DeploymentsListOptions struct {
// SHA of the Deployment.
SHA string `url:"sha,omitempty"`

// List deployments for a given ref.
// List deployments for a given ref. This can be a branch, tag, or SHA.
Ref string `url:"ref,omitempty"`

// List deployments for a given task.
Expand Down
6 changes: 3 additions & 3 deletions github/repos_statuses.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ func (r RepoStatus) String() string {
}

// ListStatuses lists the statuses of a repository at the specified
// reference. ref can be a SHA, a branch name, or a tag name.
// reference. The ref can be a SHA, a branch name, or a tag name.
//
// GitHub API docs: https://docs.github.com/rest/commits/statuses#list-commit-statuses-for-a-reference
//
Expand All @@ -70,7 +70,7 @@ func (s *RepositoriesService) ListStatuses(ctx context.Context, owner, repo, ref
}

// CreateStatus creates a new status for a repository at the specified
// reference. Ref can be a SHA, a branch name, or a tag name.
// reference. The ref can be a SHA, a branch name, or a tag name.
//
// GitHub API docs: https://docs.github.com/rest/commits/statuses#create-a-commit-status
//
Expand Down Expand Up @@ -111,7 +111,7 @@ func (s CombinedStatus) String() string {
}

// GetCombinedStatus returns the combined status of a repository at the specified
// reference. ref can be a SHA, a branch name, or a tag name.
// reference. The ref can be a SHA, a branch name, or a tag name.
//
// GitHub API docs: https://docs.github.com/rest/commits/statuses#get-the-combined-status-for-a-specific-reference
//
Expand Down
Loading