gerrit

package
v0.0.0-...-16694d9 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 4, 2021 License: BSD-3-Clause Imports: 23 Imported by: 0

README

Go Reference

golang.org/x/build/gerrit

Package gerrit contains code to interact with Gerrit servers.

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

Examples

Constants

View Source
const (
	ChangeStatusNew       = "NEW"
	ChangeStatusAbandoned = "ABANDONED"
	ChangeStatusMerged    = "MERGED"
)

Possible values for the ChangeInfo Status field.

View Source
const (
	FileInfoAdded     = "A"
	FileInfoDeleted   = "D"
	FileInfoRenamed   = "R"
	FileInfoCopied    = "C"
	FileInfoRewritten = "W"
)

Possible values for the FileInfo Status field.

Variables

View Source
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.

View Source
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.

View Source
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 BasicAuth

func BasicAuth(username, password string) Auth

BasicAuth sends a username and password.

func DigestAuth

func DigestAuth(username, password string) Auth

DigestAuth returns an Auth implementation which sends the provided username and password using HTTP Digest Authentication (RFC 2617)

func GitCookieFileAuth

func GitCookieFileAuth(file string) Auth

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"`
	Hashtags []string     `json:"hashtags"`

	// 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 ChangeMessageInfo struct {
	ID             string       `json:"id"`
	Author         *AccountInfo `json:"author"`
	Time           TimeStamp    `json:"date"`
	Message        string       `json:"message"`
	Tag            string       `json:"tag,omitempty"`
	RevisionNumber int          `json:"_revision_number"`
}

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

func NewClient(url string, auth Auth) *Client

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) 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

func (c *Client) GetAccountInfo(ctx context.Context, accountID string) (AccountInfo, error)

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 (c *Client) GetGroupMembers(ctx context.Context, groupID string) ([]AccountInfo, error)

func (*Client) GetGroups

func (c *Client) GetGroups(ctx context.Context) (map[string]*GroupInfo, error)

func (*Client) GetHashtags

func (c *Client) GetHashtags(ctx context.Context, changeID string) ([]string, error)

GetHashtags returns a CL's current hashtags.

See https://gerrit-documentation.storage.googleapis.com/Documentation/2.15.1/rest-api-changes.html#get-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

func (c *Client) GetProjectInfo(ctx context.Context, name string) (ProjectInfo, error)

GetProjectInfo returns info about a project. If the project doesn't exist, the error will be ErrProjectNotExist.

func (*Client) GetProjectTags

func (c *Client) GetProjectTags(ctx context.Context, name string) (map[string]TagInfo, error)

GetProjectTags returns the tags for the project name. The tags are stored in a map keyed by reference.

func (*Client) GetProjects

func (c *Client) GetProjects(ctx context.Context, branch string) (map[string]*ProjectInfo, error)

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

func (c *Client) ListReviewers(ctx context.Context, changeID string) ([]ReviewerInfo, error)

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.

See https://gerrit-documentation.storage.googleapis.com/Documentation/2.15.1/rest-api-changes.html#set-hashtags

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

type CommentInput struct {
	Line    int    `json:"line"`
	Message string `json:"message"`
}

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 FetchInfo

type FetchInfo struct {
	URL      string            `json:"url"`
	Ref      string            `json:"ref"`
	Commands map[string]string `json:"commands"`
}

type FileInfo

type FileInfo struct {
	Status        string `json:"status"`
	Binary        bool   `json:"binary"`
	OldPath       string `json:"old_path"`
	LinesInserted int    `json:"lines_inserted"`
	LinesDeleted  int    `json:"lines_deleted"`
}

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.

func (*HTTPError) Error

func (e *HTTPError) Error() string

type HashtagsInput

type HashtagsInput struct {
	Add    []string `json:"add"`
	Remove []string `json:"remove"`
}

HashtagsInput is the request body used when modifying a CL's hashtags.

See https://gerrit-documentation.storage.googleapis.com/Documentation/2.15.1/rest-api-changes.html#hashtags-input

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"`
	CommitWithFooters string                `json:"commit_with_footers"`
	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

func (*TagInfo) Equal

func (ti *TagInfo) Equal(v *TagInfo) bool

type TimeStamp

type TimeStamp time.Time

func (TimeStamp) Equal

func (ts TimeStamp) Equal(v TimeStamp) bool

func (TimeStamp) MarshalJSON

func (ts TimeStamp) MarshalJSON() ([]byte, error)

func (TimeStamp) Time

func (ts TimeStamp) Time() time.Time

func (*TimeStamp) UnmarshalJSON

func (ts *TimeStamp) UnmarshalJSON(p []byte) error

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL