gerritsdk

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Mar 26, 2026 License: MIT Imports: 8 Imported by: 0

README

gerrit-sdk

A high-level Go client for Gerrit Code Review, with first-class support for Googlesource.com instances.

Built on top of andygrunwald/go-gerrit, this SDK provides:

  • Googlesource authentication via .gitcookies, HTTP Basic, or Bearer tokens
  • Fluent query builder for Gerrit's change search syntax
  • Simplified types (CL, CLFile, FileDiff, Project) mapped from go-gerrit internals
  • Diff retrieval with structured content segments

Install

go get github.com/albertocavalcante/gerrit-sdk

Usage

Anonymous access (public instances)
package main

import (
    "context"
    "fmt"

    gerritsdk "github.com/albertocavalcante/gerrit-sdk"
)

func main() {
    ctx := context.Background()
    client, err := gerritsdk.NewAnonymousClient(ctx, "bazel-review.googlesource.com")
    if err != nil {
        panic(err)
    }

    query := gerritsdk.NewQuery().
        Project("bazel").
        Status("merged").
        File("docs/").
        String()

    cls, err := client.QueryChanges(ctx, query, gerritsdk.WithLimit(10))
    if err != nil {
        panic(err)
    }

    for _, cl := range cls {
        fmt.Printf("CL/%d  %s  (%s)\n", cl.Number, cl.Subject, cl.Owner)
    }
}
Authenticated access (gitcookies)
client, err := gerritsdk.NewClient(ctx, "bazel-review.googlesource.com",
    gerritsdk.WithAuth(gerritsdk.GitCookiesAuth{}), // reads ~/.gitcookies
)
Authenticated access (HTTP Basic)
client, err := gerritsdk.NewClient(ctx, "review.example.com",
    gerritsdk.WithAuth(gerritsdk.HTTPBasicAuth{
        Username: "user",
        Password: os.Getenv("GERRIT_PASSWORD"),
    }),
)
Change details and files
cl, err := client.GetChangeDetail(ctx, "318050")
fmt.Println(cl.Subject, cl.Files)

files, err := client.GetChangeFiles(ctx, "318050")
for _, f := range files {
    fmt.Printf("  %s (+%d -%d)\n", f.Path, f.Insertions, f.Deletions)
}
File diffs
diff, err := client.GetChangeDiff(ctx, "318050", "docs/run/build.mdx")
for _, seg := range diff.Content {
    // seg.Common, seg.OldOnly, seg.NewOnly
}
Query builder
q := gerritsdk.NewQuery().
    Project("bazel").
    Status("merged").
    After(time.Now().Add(-30 * 24 * time.Hour)).
    File("docs/").
    Owner("self").
    String()
// "project:bazel status:merged after:2026-02-24 file:docs/ owner:self"

Authentication

Method Use case
GitCookiesAuth{Path: "~/.gitcookies"} Googlesource.com (default path: ~/.gitcookies)
HTTPBasicAuth{Username, Password} Standard Gerrit with HTTP auth
BearerTokenAuth{Token} OAuth2 / service accounts
None (NewAnonymousClient) Public read-only access

Auth errors are returned immediately from NewClient -- the SDK never silently falls back to unauthenticated access.

Advanced usage

Access the underlying go-gerrit client for endpoints not yet wrapped:

inner := client.Inner()
reviewers, _, err := inner.Changes.ListReviewers(ctx, "318050")

License

MIT

Documentation

Overview

Package gerritsdk provides a high-level Go client for Gerrit Code Review instances, with first-class support for Googlesource.com authentication.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ParseGitCookiesForHost 

func ParseGitCookiesForHost(path, host string) (user, pass string, err error)

ParseGitCookiesForHost reads a .gitcookies file and returns credentials for the specified host.

Types

type AuthMethod 

type AuthMethod interface {
	// contains filtered or unexported methods
}

AuthMethod configures how the client authenticates with Gerrit.

type BearerTokenAuth 

type BearerTokenAuth struct {
	Token string
}

BearerTokenAuth authenticates with an OAuth2 bearer token.

type BuildQuery 

type BuildQuery struct {
	// contains filtered or unexported fields
}

BuildQuery is a helper for constructing Gerrit query strings.

func NewQuery 

func NewQuery() *BuildQuery

NewQuery starts building a query.

func (*BuildQuery) After 

func (q *BuildQuery) After(t time.Time) *BuildQuery

After restricts to changes updated after a time.

func (*BuildQuery) Before 

func (q *BuildQuery) Before(t time.Time) *BuildQuery

Before restricts to changes updated before a time.

func (*BuildQuery) File 

func (q *BuildQuery) File(path string) *BuildQuery

File restricts to changes touching a file path (prefix match).

func (*BuildQuery) Owner 

func (q *BuildQuery) Owner(user string) *BuildQuery

Owner restricts to changes owned by a user.

func (*BuildQuery) Project 

func (q *BuildQuery) Project(name string) *BuildQuery

Project restricts to a project.

func (*BuildQuery) Raw 

func (q *BuildQuery) Raw(fragment string) *BuildQuery

Raw adds a raw query fragment.

func (*BuildQuery) Status 

func (q *BuildQuery) Status(status string) *BuildQuery

Status restricts to a change status.

func (*BuildQuery) String 

func (q *BuildQuery) String() string

String returns the assembled query.

type CL 

type CL struct {
	Number    int       `json:"number"`
	Project   string    `json:"project"`
	Branch    string    `json:"branch"`
	ChangeID  string    `json:"change_id"`
	Subject   string    `json:"subject"`
	Status    string    `json:"status"` // NEW, MERGED, ABANDONED
	Owner     string    `json:"owner"`
	Created   time.Time `json:"created"`
	Updated   time.Time `json:"updated"`
	Submitted time.Time `json:"submitted,omitempty"`
	Mergeable bool      `json:"mergeable,omitempty"`
	URL       string    `json:"url"`
	Files     []string  `json:"files,omitempty"`
}

CL represents a Gerrit change (changelist).

type CLFile 

type CLFile struct {
	Path       string `json:"path"`
	Status     string `json:"status"` // ADDED, MODIFIED, DELETED, RENAMED, COPIED
	OldPath    string `json:"old_path,omitempty"`
	Insertions int    `json:"insertions"`
	Deletions  int    `json:"deletions"`
}

CLFile represents a file changed in a CL revision.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a high-level Gerrit REST API client.

func NewAnonymousClient 

func NewAnonymousClient(ctx context.Context, host string, opts ...Option) (*Client, error)

NewAnonymousClient creates an unauthenticated Gerrit client. Only public endpoints will be accessible.

func NewClient 

func NewClient(ctx context.Context, host string, opts ...Option) (*Client, error)

NewClient creates a Gerrit client for the given host. The host should be a bare hostname like "bazel-review.googlesource.com".

func (*Client) GetChangeCommitMessage 

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

GetChangeCommitMessage returns the commit message for a change.

func (*Client) GetChangeDetail 

func (c *Client) GetChangeDetail(ctx context.Context, changeID string) (*CL, error)

GetChangeDetail returns detailed information about a single change.

func (*Client) GetChangeDiff 

func (c *Client) GetChangeDiff(ctx context.Context, changeID, filePath string) (*FileDiff, error)

GetChangeDiff returns the diff for a specific file in a change.

func (*Client) GetChangeFiles 

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

GetChangeFiles returns the list of files modified in the current patchset.

func (*Client) GetProject 

func (c *Client) GetProject(ctx context.Context, name string) (*Project, error)

GetProject returns details about a specific project.

func (*Client) Host 

func (c *Client) Host() string

Host returns the Gerrit instance hostname.

func (*Client) Inner 

func (c *Client) Inner() *gogerrit.Client

Inner returns the underlying go-gerrit client for advanced usage.

func (*Client) ListProjectBranches 

func (c *Client) ListProjectBranches(ctx context.Context, project string) ([]string, error)

ListProjectBranches returns branches for a project.

func (*Client) ListProjects 

func (c *Client) ListProjects(ctx context.Context) ([]Project, error)

ListProjects returns all projects on the Gerrit instance.

func (*Client) QueryChanges 

func (c *Client) QueryChanges(ctx context.Context, query string, opts ...QueryOption) ([]CL, error)

QueryChanges searches for changes matching the given Gerrit query string. Example queries: 

"project:bazel status:merged file:docs/"
"status:open owner:self"

type DiffContent 

type DiffContent struct {
	Common  []string `json:"ab,omitempty"` // lines common to both
	OldOnly []string `json:"a,omitempty"`  // lines only in old version
	NewOnly []string `json:"b,omitempty"`  // lines only in new version
}

DiffContent represents a segment of a unified diff returned by Gerrit.

type FileDiff 

type FileDiff struct {
	Path    string        `json:"path"`
	Content []DiffContent `json:"content"`
}

FileDiff represents the diff for a single file.

type GitCookiesAuth 

type GitCookiesAuth struct {
	Path string // path to .gitcookies file; empty = ~/.gitcookies
}

GitCookiesAuth authenticates using a .gitcookies file, the standard method for googlesource.com instances.

type HTTPBasicAuth 

type HTTPBasicAuth struct {
	Username string
	Password string
}

HTTPBasicAuth authenticates with a username and password/token. 

type Link struct {
	Name string `json:"name"`
	URL  string `json:"url"`
}

Link is a Gerrit web link.

type Option 

type Option func(*clientConfig)

Option configures a Client.

func WithAuth 

func WithAuth(a AuthMethod) Option

WithAuth sets the authentication method.

func WithHTTPClient 

func WithHTTPClient(c *http.Client) Option

WithHTTPClient sets a custom http.Client for the underlying transport.

type Project 

type Project struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	State       string `json:"state"` // ACTIVE, READ_ONLY, HIDDEN
	WebLinks    []Link `json:"web_links,omitempty"`
}

Project represents a Gerrit project (repository).

type QueryOption 

type QueryOption func(*queryConfig)

QueryOption modifies a change query.

func WithFields 

func WithFields(fields ...string) QueryOption

WithFields requests additional fields (e.g. "CURRENT_REVISION", "ALL_FILES").

func WithLimit 

func WithLimit(n int) QueryOption

WithLimit sets the maximum number of results.

func WithOffset 

func WithOffset(n int) QueryOption

WithOffset sets the result offset for pagination.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.