build: Index | Examples | Files

package gerrit

import ""

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.


c := gerrit.NewClient("", gerrit.NoAuth)
info, err := c.GetProjectInfo(context.TODO(), "go")
if err != nil {



Package Files

auth.go gerrit.go


const (
    ChangeStatusNew       = "NEW"
    ChangeStatusAbandoned = "ABANDONED"
    ChangeStatusMerged    = "MERGED"

Possible values for the ChangeInfo Status field.


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.

type AccountInfo Uses

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 Uses

func (ai *AccountInfo) Equal(v *AccountInfo) bool

type ApprovalInfo Uses

type ApprovalInfo struct {
    Value int       `json:"value"`
    Date  TimeStamp `json:"date"`

type Auth Uses

type Auth interface {
    // contains filtered or unexported methods

Auth is a Gerrit authentication mode. The most common ones are NoAuth or BasicAuth.

func BasicAuth Uses

func BasicAuth(username, password string) Auth

BasicAuth sends a username and password.

func DigestAuth Uses

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 Uses

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 Uses

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 Uses

type BranchInfo struct {
    Ref       string `json:"ref"`
    Revision  string `json:"revision"`
    CanDelete bool   `json:"can_delete"`

BranchInfo is information about a branch. See

type ChangeInfo Uses

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"`

    Project string `json:"project"`

    // Branch is the name of the target branch.
    // The refs/heads/ prefix is omitted.
    Branch string `json:"branch"`

    ChangeID string `json:"change_id"`

    Subject string `json:"subject"`

    // Status is the status of the change (NEW, SUBMITTED, MERGED,
    Status string `json:"status"`

    Created  TimeStamp `json:"created"`
    Updated  TimeStamp `json:"updated"`
    Mergable bool      `json:"mergable"`

    // 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
    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 map[string]LabelInfo `json:"labels"`

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

type ChangeMessageInfo Uses

type ChangeMessageInfo struct {
    ID             string       `json:"id"`
    Author         *AccountInfo `json:"author"`
    Time           TimeStamp    `json:"date"`
    Message        string       `json:"message"`
    RevisionNumber int          `json:"_revision_number"`

type Client Uses

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 Uses

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. If auth is nil, a default is used, or requests are made unauthenticated.

func (*Client) AbandonChange Uses

func (c *Client) AbandonChange(ctx context.Context, changeID string, message ...string) error

AbandonChange abandons the given change. For the API call, see The changeID is The input for the call is

func (*Client) AddHashtags Uses

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 Uses

func (c *Client) CreateProject(ctx context.Context, name string, p ...ProjectInput) (ProjectInfo, error)

CreateProject creates a new project.

func (*Client) GetAccountInfo Uses

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 The accountID is

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 Uses

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 If the change doesn't exist, the error will be ErrChangeNotExist.

func (*Client) GetChangeDetail Uses

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

func (*Client) GetGroupMembers Uses

func (c *Client) GetGroupMembers(ctx context.Context, groupID string) ([]AccountInfo, error)

func (*Client) GetGroups Uses

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

func (*Client) GetHashtags Uses

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

GetHashtags returns a CL's current hashtags.


func (*Client) GetProjectBranches Uses

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

GetProjectBranches returns a project's branches.

func (*Client) GetProjectInfo Uses

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

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

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.


func (*Client) QueryAccounts Uses

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

func (*Client) QueryChanges Uses

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 For the query syntax, see

func (*Client) RemoveHashtags Uses

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 Uses

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 Uses

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 The changeID is The revision is

type CommentInput Uses

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

CommentInput contains information for creating an inline comment. See

type CommitInfo Uses

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 Uses

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

type FileInfo Uses

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 Uses

type GitPersonInfo struct {
    Name     string    `json:"name"`
    Email    string    `json:"Email"`
    Date     TimeStamp `json:"date"`
    TZOffset int       `json:"tz"`

type GroupInfo Uses

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.


type GroupOptionsInfo Uses

type GroupOptionsInfo struct {
    VisibleToAll bool `json:"visible_to_all"`

type HTTPError Uses

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 Uses

func (e *HTTPError) Error() string

type HashtagsInput Uses

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

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


type LabelInfo Uses

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 Uses

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

type ProjectInput Uses

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

type QueryAccountsOpt Uses

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:
    Fields []string

QueryAccountsOpt are options for QueryAccounts.

type QueryChangesOpt Uses

type QueryChangesOpt struct {
    // N is the number of results to return.
    // If 0, the 'n' parameter is not sent to Gerrit.
    N   int

    // Fields are optional fields to also return.
    // Example strings include "ALL_REVISIONS", "LABELS", "MESSAGES".
    // For a complete list, see:
    Fields []string

QueryChangesOpt are options for QueryChanges.

type ReviewInput Uses

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"`

ReviewInput contains information for adding a review to a revision. See

type RevisionInfo Uses

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"`

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:

type TimeStamp Uses

type TimeStamp time.Time

func (TimeStamp) MarshalJSON Uses

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

func (TimeStamp) Time Uses

func (ts TimeStamp) Time() time.Time

func (*TimeStamp) UnmarshalJSON Uses

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

Package gerrit imports 22 packages (graph) and is imported by 15 packages. Updated 2018-05-22. Refresh now. Tools for package owners.