Skip to content

Commit 5b41764

Browse files
authored
docs: Extend the description of ref parameters (#3643)
1 parent 74b2ca0 commit 5b41764

File tree

5 files changed

+19
-7
lines changed

5 files changed

+19
-7
lines changed

example/commitpr/main.go

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ var ctx = context.Background()
6363
// getRef returns the commit branch reference object if it exists or creates it
6464
// from the base branch before returning it.
6565
func getRef() (ref *github.Reference, err error) {
66-
if ref, _, err = client.Git.GetRef(ctx, *sourceOwner, *sourceRepo, "refs/heads/"+*commitBranch); err == nil {
66+
if ref, _, err = client.Git.GetRef(ctx, *sourceOwner, *sourceRepo, branchRef(*commitBranch)); err == nil {
6767
return ref, nil
6868
}
6969

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

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

89+
// branchRef generates the fully qualified git reference for the given branch name.
90+
func branchRef(name string) string {
91+
return "refs/heads/" + name
92+
}
93+
8994
// getTree generates the tree to commit based on the given files and the commit
9095
// of the ref you got in getRef.
9196
func getTree(ref *github.Reference) (tree *github.Tree, err error) {

github/checks.go

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -269,6 +269,8 @@ type ListCheckRunsResults struct {
269269
}
270270

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

359361
// ListCheckSuitesForRef lists check suite for a specific ref.
362+
// The ref can be a commit SHA, branch name `heads/<branch name>`, or tag name `tags/<tag name>`.
363+
// For more information, see "Git References" in the Git documentation https://git-scm.com/book/en/v2/Git-Internals-Git-References.
360364
//
361365
// GitHub API docs: https://docs.github.com/rest/checks/suites#list-check-suites-for-a-git-reference
362366
//

github/git_refs.go

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ import (
1414

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

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

8790
ListOptions

github/repos_deployments.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ type DeploymentsListOptions struct {
4949
// SHA of the Deployment.
5050
SHA string `url:"sha,omitempty"`
5151

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

5555
// List deployments for a given task.

github/repos_statuses.go

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ func (r RepoStatus) String() string {
4343
}
4444

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

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

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

0 commit comments

Comments
 (0)