Documentation ¶
Overview ¶
Package gerrit contains code to interact with Gerrit servers.
The API is not subject to the Go 1 compatibility promise and may change at any time.
Example ¶
package main import ( "context" "fmt" "golang.org/x/build/gerrit" ) func main() { c := gerrit.NewClient("https://go-review.googlesource.com", gerrit.NoAuth) info, err := c.GetProjectInfo(context.TODO(), "go") if err != nil { panic(err) } fmt.Println(info.Description) }
Output:
Index ¶
- Constants
- Variables
- type AccountInfo
- type ApprovalInfo
- type Auth
- type BranchInfo
- type ChangeInfo
- type ChangeMessageInfo
- type Client
- func (c *Client) AbandonChange(ctx context.Context, changeID string, message ...string) error
- func (c *Client) AddHashtags(ctx context.Context, changeID string, tags ...string) ([]string, error)
- func (c *Client) CreateProject(ctx context.Context, name string, p ...ProjectInput) (ProjectInfo, error)
- func (c *Client) GetAccountInfo(ctx context.Context, accountID string) (AccountInfo, error)
- func (c *Client) GetChange(ctx context.Context, changeID string, opts ...QueryChangesOpt) (*ChangeInfo, error)
- func (c *Client) GetChangeDetail(ctx context.Context, changeID string, opts ...QueryChangesOpt) (*ChangeInfo, error)
- func (c *Client) GetGroupMembers(ctx context.Context, groupID string) ([]AccountInfo, error)
- func (c *Client) GetGroups(ctx context.Context) (map[string]*GroupInfo, error)
- func (c *Client) GetHashtags(ctx context.Context, changeID string) ([]string, error)
- func (c *Client) GetProjectBranches(ctx context.Context, name string) (map[string]BranchInfo, error)
- func (c *Client) GetProjectInfo(ctx context.Context, name string) (ProjectInfo, error)
- func (c *Client) GetProjectTags(ctx context.Context, name string) (map[string]TagInfo, error)
- func (c *Client) GetProjects(ctx context.Context, branch string) (map[string]*ProjectInfo, error)
- func (c *Client) ListChangeComments(ctx context.Context, changeID string) (map[string][]CommentInfo, error)
- func (c *Client) ListFiles(ctx context.Context, changeID, revision string) (map[string]*FileInfo, error)
- func (c *Client) ListProjects(ctx context.Context) ([]ProjectInfo, error)
- func (c *Client) ListReviewers(ctx context.Context, changeID string) ([]ReviewerInfo, error)
- func (c *Client) QueryAccounts(ctx context.Context, q string, opts ...QueryAccountsOpt) ([]*AccountInfo, error)
- func (c *Client) QueryChanges(ctx context.Context, q string, opts ...QueryChangesOpt) ([]*ChangeInfo, error)
- func (c *Client) RemoveHashtags(ctx context.Context, changeID string, tags ...string) ([]string, error)
- func (c *Client) SetHashtags(ctx context.Context, changeID string, hashtags HashtagsInput) ([]string, error)
- func (c *Client) SetReview(ctx context.Context, changeID, revision string, review ReviewInput) error
- type CommentInfo
- type CommentInput
- type CommitInfo
- type FetchInfo
- type FileInfo
- type GitPersonInfo
- type GroupInfo
- type GroupOptionsInfo
- type HTTPError
- type HashtagsInput
- type LabelInfo
- type ProjectInfo
- type ProjectInput
- type QueryAccountsOpt
- type QueryChangesOpt
- type ReviewInput
- type ReviewerInfo
- type ReviewerInput
- type ReviewerUpdateInfo
- type RevisionInfo
- type TagInfo
- type TimeStamp
- type WebLinkInfo
Examples ¶
Constants ¶
const ( ChangeStatusNew = "NEW" ChangeStatusAbandoned = "ABANDONED" ChangeStatusMerged = "MERGED" )
Possible values for the ChangeInfo Status field.
const ( FileInfoAdded = "A" FileInfoDeleted = "D" FileInfoRenamed = "R" FileInfoCopied = "C" FileInfoRewritten = "W" )
Possible values for the FileInfo Status field.
Variables ¶
var ErrChangeNotExist = errors.New("gerrit: requested change does not exist")
ErrChangeNotExist is returned when a change doesn't exist. It is not necessarily returned unless a method is documented as returning it.
var ErrProjectNotExist = errors.New("gerrit: requested project does not exist")
ErrProjectNotExist is returned when a project doesn't exist. It is not necessarily returned unless a method is documented as returning it.
var NoAuth = noAuth{}
NoAuth makes requests unauthenticated.
Functions ¶
This section is empty.
Types ¶
type AccountInfo ¶
type AccountInfo struct { NumericID int64 `json:"_account_id"` Name string `json:"name,omitempty"` Email string `json:"email,omitempty"` Username string `json:"username,omitempty"` // MoreAccounts is set on the last account from QueryAccounts if // the result set is truncated by an 'n' parameter (or has more). MoreAccounts bool `json:"_more_accounts"` }
AccountInfo is a Gerrit data structure. It's used both for getting the details for a single account, as well as for querying multiple accounts.
func (*AccountInfo) Equal ¶
func (ai *AccountInfo) Equal(v *AccountInfo) bool
type ApprovalInfo ¶
type ApprovalInfo struct { AccountInfo Value int `json:"value"` Date TimeStamp `json:"date"` }
type Auth ¶
type Auth interface {
// contains filtered or unexported methods
}
Auth is a Gerrit authentication mode. The most common ones are NoAuth or BasicAuth.
func DigestAuth ¶
DigestAuth returns an Auth implementation which sends the provided username and password using HTTP Digest Authentication (RFC 2617)
func GitCookieFileAuth ¶
GitCookieFileAuth derives the Gerrit authentication token from the provided gitcookies file. It is equivalent to GitCookiesAuth, except that "git config http.cookiefile" is not used to find which cookie file to use.
func GitCookiesAuth ¶
func GitCookiesAuth() Auth
GitCookiesAuth derives the Gerrit authentication token from gitcookies based on the URL of the Gerrit request. The cookie file used is determined by running "git config http.cookiefile" in the current directory. To use a specific file, see GitCookieFileAuth.
type BranchInfo ¶
type BranchInfo struct { Ref string `json:"ref"` Revision string `json:"revision"` CanDelete bool `json:"can_delete"` }
BranchInfo is information about a branch. See https://gerrit-review.googlesource.com/Documentation/rest-api-projects.html#branch-info
type ChangeInfo ¶
type ChangeInfo struct { // ID is the ID of the change in the format // "'<project>~<branch>~<Change-Id>'", where 'project', // 'branch' and 'Change-Id' are URL encoded. For 'branch' the // refs/heads/ prefix is omitted. ID string `json:"id"` ChangeNumber int `json:"_number"` ChangeID string `json:"change_id"` Project string `json:"project"` // Branch is the name of the target branch. // The refs/heads/ prefix is omitted. Branch string `json:"branch"` Topic string `json:"topic"` Assignee *AccountInfo `json:"assignee"` // Subject is the subject of the change // (the header line of the commit message). Subject string `json:"subject"` // Status is the status of the change (NEW, SUBMITTED, MERGED, // ABANDONED, DRAFT). Status string `json:"status"` Created TimeStamp `json:"created"` Updated TimeStamp `json:"updated"` Submitted TimeStamp `json:"submitted"` Submitter *AccountInfo `json:"submitter"` SubmitType string `json:"submit_type"` // Mergeable indicates whether the change can be merged. // It is not set for already-merged changes, // nor if the change is untested, nor if the // SKIP_MERGEABLE option has been set. Mergeable bool `json:"mergeable"` // Submittable indicates whether the change can be submitted. // It is only set if requested, using the "SUBMITTABLE" option. Submittable bool `json:"submittable"` // Insertions and Deletions count inserted and deleted lines. Insertions int `json:"insertions"` Deletions int `json:"deletions"` // CurrentRevision is the commit ID of the current patch set // of this change. This is only set if the current revision // is requested or if all revisions are requested (fields // "CURRENT_REVISION" or "ALL_REVISIONS"). CurrentRevision string `json:"current_revision"` // Revisions maps a commit ID of the patch set to a // RevisionInfo entity. // // Only set if the current revision is requested (in which // case it will only contain a key for the current revision) // or if all revisions are requested. Revisions map[string]RevisionInfo `json:"revisions"` // Owner is the author of the change. // The details are only filled in if field "DETAILED_ACCOUNTS" is requested. Owner *AccountInfo `json:"owner"` // Messages are included if field "MESSAGES" is requested. Messages []ChangeMessageInfo `json:"messages"` // Labels maps label names to LabelInfo entries. Labels map[string]LabelInfo `json:"labels"` // ReviewerUpdates are included if field "REVIEWER_UPDATES" is requested. ReviewerUpdates []ReviewerUpdateInfo `json:"reviewer_updates"` // Reviewers maps reviewer state ("REVIEWER", "CC", "REMOVED") // to a list of accounts. // REVIEWER lists users with at least one non-zero vote on the change. // CC lists users added to the change who has not voted. // REMOVED lists users who were previously reviewers on the change // but who have been removed. // Reviewers is only included if "DETAILED_LABELS" is requested. Reviewers map[string][]*AccountInfo `json:"reviewers"` // WorkInProgress indicates that the change is marked as a work in progress. // (This means it is not yet ready for review, but it is still publicly visible.) WorkInProgress bool `json:"work_in_progress"` // HasReviewStarted indicates whether the change has ever been marked // ready for review in the past (not as a work in progress). HasReviewStarted bool `json:"has_review_started"` // RevertOf lists the numeric Change-Id of the change that this change reverts. RevertOf int `json:"revert_of"` // MoreChanges is set on the last change from QueryChanges if // the result set is truncated by an 'n' parameter. MoreChanges bool `json:"_more_changes"` }
ChangeInfo is a Gerrit data structure. See https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#change-info
type ChangeMessageInfo ¶
type Client ¶
type Client struct { // HTTPClient optionally specifies an HTTP client to use // instead of http.DefaultClient. HTTPClient *http.Client // contains filtered or unexported fields }
Client is a Gerrit client.
func NewClient ¶
NewClient returns a new Gerrit client with the given URL prefix and authentication mode. The url should be just the scheme and hostname. For example, "https://go-review.googlesource.com". If auth is nil, a default is used, or requests are made unauthenticated.
func (*Client) AbandonChange ¶
AbandonChange abandons the given change. For the API call, see https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#abandon-change The changeID is https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#change-id The input for the call is https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#abandon-input
func (*Client) AddHashtags ¶
func (c *Client) AddHashtags(ctx context.Context, changeID string, tags ...string) ([]string, error)
AddHashtags is a wrapper around SetHashtags that only supports adding tags.
func (*Client) CreateProject ¶
func (c *Client) CreateProject(ctx context.Context, name string, p ...ProjectInput) (ProjectInfo, error)
CreateProject creates a new project.
func (*Client) GetAccountInfo ¶
GetAccountInfo gets the specified account's information from Gerrit. For the API call, see https://gerrit-review.googlesource.com/Documentation/rest-api-accounts.html#get-account The accountID is https://gerrit-review.googlesource.com/Documentation/rest-api-accounts.html#account-id
Note that getting "self" is a good way to validate host access, since it only requires peeker access to the host, not to any particular repository.
func (*Client) GetChange ¶
func (c *Client) GetChange(ctx context.Context, changeID string, opts ...QueryChangesOpt) (*ChangeInfo, error)
GetChange returns information about a single change. For the API call, see https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#get-change If the change doesn't exist, the error will be ErrChangeNotExist.
func (*Client) GetChangeDetail ¶
func (c *Client) GetChangeDetail(ctx context.Context, changeID string, opts ...QueryChangesOpt) (*ChangeInfo, error)
GetChangeDetail retrieves a change with labels, detailed labels, detailed accounts, and messages. For the API call, see https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#get-change-detail
func (*Client) GetGroupMembers ¶
func (*Client) GetHashtags ¶
GetHashtags returns a CL's current hashtags.
func (*Client) GetProjectBranches ¶
func (c *Client) GetProjectBranches(ctx context.Context, name string) (map[string]BranchInfo, error)
GetProjectBranches returns the branches for the project name. The branches are stored in a map keyed by reference.
func (*Client) GetProjectInfo ¶
GetProjectInfo returns info about a project. If the project doesn't exist, the error will be ErrProjectNotExist.
func (*Client) GetProjectTags ¶
GetProjectTags returns the tags for the project name. The tags are stored in a map keyed by reference.
func (*Client) GetProjects ¶
GetProjects returns a map of all projects on the Gerrit server.
func (*Client) ListChangeComments ¶
func (c *Client) ListChangeComments(ctx context.Context, changeID string) (map[string][]CommentInfo, error)
ListChangeComments retrieves a map of published comments for the given change ID. The map key is the file path (such as "maintner/git_test.go" or "/PATCHSET_LEVEL"). For the API call, see https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#list-change-comments.
func (*Client) ListFiles ¶
func (c *Client) ListFiles(ctx context.Context, changeID, revision string) (map[string]*FileInfo, error)
ListFiles retrieves a map of filenames to FileInfo's for the given change ID and revision. For the API call, see https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#list-files
func (*Client) ListProjects ¶
func (c *Client) ListProjects(ctx context.Context) ([]ProjectInfo, error)
ListProjects returns the server's active projects.
The returned slice is sorted by project ID and excludes the "All-Projects" project.
See https://gerrit-review.googlesource.com/Documentation/rest-api-projects.html#list-projects
func (*Client) ListReviewers ¶
ListReviewers returns all reviewers on a change. For the API call, see https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#list-reviewers The changeID is https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#change-id
func (*Client) QueryAccounts ¶
func (c *Client) QueryAccounts(ctx context.Context, q string, opts ...QueryAccountsOpt) ([]*AccountInfo, error)
QueryAccounts queries accounts. The q parameter is a Gerrit search query. For the API call and query syntax, see https://gerrit-review.googlesource.com/Documentation/rest-api-accounts.html#query-account
func (*Client) QueryChanges ¶
func (c *Client) QueryChanges(ctx context.Context, q string, opts ...QueryChangesOpt) ([]*ChangeInfo, error)
QueryChanges queries changes. The q parameter is a Gerrit search query. For the API call, see https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#list-changes For the query syntax, see https://gerrit-review.googlesource.com/Documentation/user-search.html#_search_operators
func (*Client) RemoveHashtags ¶
func (c *Client) RemoveHashtags(ctx context.Context, changeID string, tags ...string) ([]string, error)
RemoveHashtags is a wrapper around SetHashtags that only supports removing tags.
func (*Client) SetHashtags ¶
func (c *Client) SetHashtags(ctx context.Context, changeID string, hashtags HashtagsInput) ([]string, error)
SetHashtags modifies the hashtags for a CL, supporting both adding and removing hashtags in one request. On success it returns the new set of hashtags.
func (*Client) SetReview ¶
func (c *Client) SetReview(ctx context.Context, changeID, revision string, review ReviewInput) error
SetReview leaves a message on a change and/or modifies labels. For the API call, see https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#set-review The changeID is https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#change-id The revision is https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#revision-id
type CommentInfo ¶
type CommentInfo struct { PatchSet int `json:"patch_set,omitempty"` ID string `json:"id"` Path string `json:"path,omitempty"` Message string `json:"message,omitempty"` Updated TimeStamp `json:"updated"` Author *AccountInfo `json:"author,omitempty"` }
CommentInfo contains information about an inline comment. See https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#comment-info.
type CommentInput ¶
CommentInput contains information for creating an inline comment. See https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#comment-input
type CommitInfo ¶
type CommitInfo struct { Author GitPersonInfo `json:"author"` Committer GitPersonInfo `json:"committer"` CommitID string `json:"commit"` Subject string `json:"subject"` Message string `json:"message"` Parents []CommitInfo `json:"parents"` }
type GitPersonInfo ¶
type GitPersonInfo struct { Name string `json:"name"` Email string `json:"Email"` Date TimeStamp `json:"date"` TZOffset int `json:"tz"` }
func (*GitPersonInfo) Equal ¶
func (gpi *GitPersonInfo) Equal(v *GitPersonInfo) bool
type GroupInfo ¶
type GroupInfo struct { ID string `json:"id"` URL string `json:"url"` Name string `json:"name"` GroupID int64 `json:"group_id"` Options GroupOptionsInfo `json:"options"` Owner string `json:"owner"` OwnerID string `json:"owner_id"` }
GroupInfo contains information about a group.
See https://gerrit-review.googlesource.com/Documentation/rest-api-groups.html#group-info.
type GroupOptionsInfo ¶
type GroupOptionsInfo struct {
VisibleToAll bool `json:"visible_to_all"`
}
type HTTPError ¶
type HTTPError struct { Res *http.Response Body []byte // 4KB prefix BodyErr error // any error reading Body }
HTTPError is the error type returned when a Gerrit API call does not return the expected status.
type HashtagsInput ¶
type HashtagsInput struct {}
HashtagsInput is the request body used when modifying a CL's hashtags.
type LabelInfo ¶
type LabelInfo struct { // Optional means the label may be set, but it’s neither // necessary for submission nor does it block submission if // set. Optional bool `json:"optional"` All []ApprovalInfo `json:"all"` }
The LabelInfo entity contains information about a label on a change, always corresponding to the current patch set.
There are two options that control the contents of LabelInfo: LABELS and DETAILED_LABELS.
For a quick summary of the state of labels, use LABELS.
For detailed information about labels, including exact numeric votes for all users and the allowed range of votes for the current user, use DETAILED_LABELS.
type ProjectInfo ¶
type ProjectInfo struct { ID string `json:"id"` Name string `json:"name"` Parent string `json:"parent"` CloneURL string `json:"clone_url"` Description string `json:"description"` State string `json:"state"` Branches map[string]string `json:"branches"` }
ProjectInfo is information about a Gerrit project. See https://gerrit-review.googlesource.com/Documentation/rest-api-projects.html#project-info
type ProjectInput ¶
type ProjectInput struct { Parent string `json:"parent,omitempty"` Description string `json:"description,omitempty"` SubmitType string `json:"submit_type,omitempty"` CreateNewChangeForAllNotInTarget string `json:"create_new_change_for_all_not_in_target,omitempty"` }
ProjectInput contains the options for creating a new project. See https://gerrit-review.googlesource.com/Documentation/rest-api-projects.html#project-input
type QueryAccountsOpt ¶
type QueryAccountsOpt struct { // N is the number of results to return. // If 0, the 'n' parameter is not sent to Gerrit. N int // Start is the number of results to skip (useful in pagination). // To figure out if there are more results, the last AccountInfo struct // in the last call to QueryAccounts will have the field MoreAccounts=true. // If 0, the 'S' parameter is not sent to Gerrit. Start int // Fields are optional fields to also return. // Example strings include "DETAILS", "ALL_EMAILS". // By default, only the account IDs are returned. // For a complete list, see: // https://gerrit-review.googlesource.com/Documentation/rest-api-accounts.html#query-account Fields []string }
QueryAccountsOpt are options for QueryAccounts.
type QueryChangesOpt ¶
type QueryChangesOpt struct { // N is the number of results to return. // If 0, the 'n' parameter is not sent to Gerrit. N int // Start is the number of results to skip (useful in pagination). // To figure out if there are more results, the last ChangeInfo struct // in the last call to QueryChanges will have the field MoreAccounts=true. // If 0, the 'S' parameter is not sent to Gerrit. Start int // Fields are optional fields to also return. // Example strings include "ALL_REVISIONS", "LABELS", "MESSAGES". // For a complete list, see: // https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#change-info Fields []string }
QueryChangesOpt are options for QueryChanges.
type ReviewInput ¶
type ReviewInput struct { Message string `json:"message,omitempty"` Labels map[string]int `json:"labels,omitempty"` // Comments contains optional per-line comments to post. // The map key is a file path (such as "src/foo/bar.go"). Comments map[string][]CommentInput `json:"comments,omitempty"` // Reviewers optionally specifies new reviewers to add to the change. Reviewers []ReviewerInput `json:"reviewers,omitempty"` }
ReviewInput contains information for adding a review to a revision. See https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#review-input
type ReviewerInfo ¶
type ReviewerInfo struct { AccountInfo Approvals map[string]string `json:"approvals"` }
ReviewerInfo contains information about reviewers of a change. See https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#reviewer-info
type ReviewerInput ¶
type ReviewerInput struct { // Reviewer is the ID of the account to be added as reviewer. // See https://gerrit-review.googlesource.com/Documentation/rest-api-accounts.html#account-id Reviewer string `json:"reviewer"` State string `json:"state,omitempty"` // REVIEWER or CC (default: REVIEWER) }
ReviewerInput contains information for adding a reviewer to a change. See https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#reviewer-input
type ReviewerUpdateInfo ¶
type ReviewerUpdateInfo struct { Updated TimeStamp `json:"updated"` UpdatedBy *AccountInfo `json:"updated_by"` Reviewer *AccountInfo `json:"reviewer"` State string // "REVIEWER", "CC", or "REMOVED" }
ReviewerUpdateInfo is a Gerrit data structure. See https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#review-update-info
type RevisionInfo ¶
type RevisionInfo struct { Draft bool `json:"draft"` PatchSetNumber int `json:"_number"` Created TimeStamp `json:"created"` Uploader *AccountInfo `json:"uploader"` Ref string `json:"ref"` Fetch map[string]*FetchInfo `json:"fetch"` Commit *CommitInfo `json:"commit"` Files map[string]*FileInfo `json:"files"` Kind string `json:"kind"` }
The RevisionInfo entity contains information about a patch set. Not all fields are returned by default. Additional fields can be obtained by adding o parameters as described at: https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#list-changes
type TagInfo ¶
type TagInfo struct { Ref string `json:"ref"` Revision string `json:"revision"` Object string `json:"object,omitempty"` Message string `json:"message,omitempty"` Tagger *GitPersonInfo `json:"tagger,omitempty"` Created TimeStamp `json:"created,omitempty"` CanDelete bool `json:"can_delete"` WebLinks []WebLinkInfo `json:"web_links,omitempty"` }
TagInfo is information about a tag. See https://gerrit-review.googlesource.com/Documentation/rest-api-projects.html#tag-info
type WebLinkInfo ¶
type WebLinkInfo struct { Name string `json:"name"` URL string `json:"url"` ImageURL string `json:"image_url"` }
WebLinkInfo is information about a web link. See https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#web-link-info
func (*WebLinkInfo) Equal ¶
func (wli *WebLinkInfo) Equal(v *WebLinkInfo) bool