git

type APIError ¶

type APIError struct {
	Provider   string
	Method     string
	URL        string
	StatusCode int
	Body       string
}

APIError is a non-2xx provider API response.

func (e *APIError) Error() string

type Auth ¶

type Auth struct {
	Username   string
	Password   string
	Token      string
	PrivateKey string
	TLS        TLS
}

Auth carries a repository's credentials. HTTP(S) uses Username/Password or Token (sent as Basic auth with the provider's token user); SSH uses PrivateKey, with Password as its passphrase.

func (a Auth) Validate() error

type Cache ¶

type Cache struct {
	Root string
}

Cache keeps one bare mirror per repository and worktrees per ref:

<Root>/<RepoURL.CacheKey>/mirror.git
<Root>/<RepoURL.CacheKey>/mirror.lock
<Root>/<RepoURL.CacheKey>/worktrees/<ref dir>[.lock]

mirror.lock serializes fetches and worktree bookkeeping; each worktree is leased exclusively until Release, so concurrent checkouts of different refs proceed while a second checkout of the same ref waits.

func (c *Cache) Apply(ctx context.Context, repo *Repository, request ChangeRequest) (ChangeResult, error)

func (c *Cache) Checkout(ctx context.Context, repo *Repository, options CheckoutOptions) (*Worktree, error)

func (c *Cache) Compare(ctx context.Context, repo *Repository, base, head string) (Comparison, error)

func (c *Cache) Log(ctx context.Context, repo *Repository, base, head string, options LogOptions) ([]Commit, error)

type ChangeRequest ¶

type ChangeRequest struct {
	Base               string
	BaseSHA            string
	Branch             string
	Message            string
	Author             Signature
	CherryPick         []string
	CherryPickMainline int
	AllowEmpty         bool
	Trailers           []string
	Files              []FileChange
	PullRequest        *PullRequestRequest
	Tag                *TagOptions
}

ChangeRequest commits Files on a new Branch cut from Base, pushes it and, optionally, tags the commit and opens a pull request into Base.

BaseSHA, when set, pins the change to the commit the caller verified Files against: the branch is cut from exactly that commit, and a Base whose head is anywhere else fails with ErrBaseMoved before anything is pushed.

CherryPick replays full commit SHAs in order onto the branch (git cherry-pick -x, Author as committer, the original author kept) before Files are committed; Files may then be empty. A conflict aborts with *CherryPickConflictError, a merge commit needs CherryPickMainline (the 1-based parent to replay it against), and a commit already on the base is *CherryPickEmptyError unless AllowEmpty skips it. Trailers ("Key: value" lines) are appended to every replayed commit's message, after its origin line; Message is the message of the Files commit only. Nothing is pushed on any failure.

type ChangeResult ¶

type ChangeResult struct {
	Branch             string
	CommitSHA          string
	PullRequest        *PullRequest
	Tag                string
	SkippedCherryPicks []string
}

ChangeResult is what Apply pushed and opened. SkippedCherryPicks are the CherryPick commits AllowEmpty skipped as already applied.

type CheckoutOptions ¶

type CheckoutOptions struct {
	Ref       string
	Depth     int
	Ephemeral bool
}

CheckoutOptions configures Cache.Checkout. Ref is a branch, tag, full ref or 40-char SHA (empty is the remote HEAD). An Ephemeral worktree gets a unique directory removed on Release.

type CherryPickConflictError ¶

type CherryPickConflictError struct {
	Commit string
	Files  []string
}

CherryPickConflictError is a ChangeRequest.CherryPick commit that does not apply cleanly onto the base: the cherry-pick was aborted and nothing was pushed. Files are the paths left unmerged.

func (e *CherryPickConflictError) Error() string

type CherryPickEmptyError ¶

type CherryPickEmptyError struct {
	Commit string
	Base   string
}

CherryPickEmptyError is a ChangeRequest.CherryPick commit whose changes are already on Base (its patch was applied there before): the cherry-pick was aborted and nothing was pushed.

func (e *CherryPickEmptyError) Error() string

type Client ¶

type Client struct {
	Type     string
	Provider Provider
	Auth     Auth
	// contains filtered or unexported fields
}

Client is a git connection: its provider API and the credentials for its repositories.

func FromConnection(ctx dbcontext.Context, conn models.Connection) (*Client, error)

func (c *Client) Repository(rawURL string) (*Repository, error)

type CloneOptions ¶

type CloneOptions struct {
	Dir   string
	Ref   string
	Depth int
}

CloneOptions configures Clone. An empty Ref is the remote HEAD; Depth 0 fetches full history.

type Commit ¶

type Commit struct {
	SHA      string
	ShortSHA string
	Subject  string
	Body     string
	Author   Signature
	Date     time.Time
	Parents  []string
	Files    []string
}

Commit is one commit as Cache.Log reads it. Files are the paths it changed against its first parent; a merge commit (len(Parents) > 1) lists none.

func (c Commit) IsMerge() bool

type CommitOptions ¶

type CommitOptions struct {
	Message string
	Author  Signature
}

CommitOptions configures Worktree.Commit.

type Comparison ¶

type Comparison struct {
	Ahead     int
	Behind    int
	MergeBase string
}

Comparison is how head relates to base: Ahead commits on head not on base, Behind commits on base not on head, and their merge base.

type DirtyStats ¶

type DirtyStats struct {
	Staged    int
	Unstaged  int
	Untracked int
	Conflicts int
}

func (s DirtyStats) Clean() bool

type FileChange ¶

type FileChange struct {
	Path    string
	Content []byte
	Delete  bool
}

FileChange writes Content to Path, or deletes Path when Delete is set.

type InspectOptions ¶

type InspectOptions struct {
	RepositoryHint string
	BranchHint     string
}

InspectOptions carries the requested URL and ref, which a detached cache worktree cannot report itself.

type LastCommit ¶

type LastCommit struct {
	Subject     string
	Author      string
	CommittedAt time.Time
}

type ListRepositoriesOptions ¶

type ListRepositoriesOptions struct {
	Namespace string
}

ListRepositoriesOptions scopes ListRepositories. Namespace is a GitHub owner, GitLab group or Azure DevOps project; empty uses the connection's configured namespace, else every repository the credentials can see.

type LogOptions ¶

type LogOptions struct {
	Limit int
	Paths []string
}

LogOptions configures Cache.Log. Limit > 0 keeps only the newest Limit commits; Paths keeps only the commits that touch them.

type Metadata ¶

type Metadata struct {
	Repository string
	Branch     string
	SHA        string
	Dirty      DirtyStats
	LastCommit LastCommit
}

func Inspect(ctx context.Context, dir string, options InspectOptions) (Metadata, error)

type Provider ¶

type Provider interface {
	// Type is the models.ConnectionType* of the provider.
	Type() string
	// Verify checks the credentials against the provider.
	Verify(ctx context.Context) error
	ListRepositories(ctx context.Context, options ListRepositoriesOptions) ([]RepositoryInfo, error)
	// SupportsPullRequests reports whether OpenPullRequest can succeed, so a
	// change can be refused before anything is pushed.
	SupportsPullRequests() bool
	OpenPullRequest(ctx context.Context, repo RepoURL, request PullRequestRequest) (PullRequest, error)
	GetPullRequest(ctx context.Context, repo RepoURL, number int) (PullRequest, error)
	ClosePullRequest(ctx context.Context, repo RepoURL, number int) error
}

Provider is a git hosting provider's REST API.

type PullRequest ¶

type PullRequest struct {
	Number int
	URL    string
	State  PullRequestState
	Head   string
	Base   string
	Title  string
}

PullRequest is an opened pull (or merge) request.

type PullRequestRequest ¶

type PullRequestRequest struct {
	Title     string
	Body      string
	Head      string
	Base      string
	Draft     bool
	Labels    []string
	Assignees []string
	Reviewers []string
	AutoMerge bool
}

PullRequestRequest opens a pull request from Head into Base.

type PullRequestState ¶

type PullRequestState string

PullRequestState is a provider-neutral pull request state.

const (
	PullRequestOpen   PullRequestState = "open"
	PullRequestClosed PullRequestState = "closed"
	PullRequestMerged PullRequestState = "merged"
)

type PushOptions ¶

type PushOptions struct {
	Branch        string
	RemoteBranch  string
	Tags          []string
	Force         bool
	ExpectedSHA   string
	ServerOptions []string
}

PushOptions configures Worktree.Push. Branch is a local branch pushed to RemoteBranch (default: the same name). A push never overwrites history unless Force is set, and then only with --force-with-lease against ExpectedSHA. ServerOptions are sent as git push options (-o).

type Ref ¶

type Ref struct {
	Name      string
	FullName  string
	SHA       string
	Kind      RefKind
	Annotated bool
}

Ref is a remote ref resolved to a commit. For an annotated tag SHA is the peeled commit and Annotated is set.

func Clone(ctx context.Context, repo *Repository, options CloneOptions) (Ref, error)

type RefKind ¶

type RefKind string

RefKind is what a resolved ref names.

const (
	RefBranch RefKind = "branch"
	RefTag    RefKind = "tag"
	// RefHead is a remote HEAD that is not a symbolic ref to a branch.
	RefHead RefKind = "head"
	// RefSHA is a full commit SHA given directly.
	RefSHA RefKind = "sha"
)

type RemoteRefs ¶

type RemoteRefs struct {
	Head     *Ref
	Branches []Ref
	Tags     []Ref
}

RemoteRefs are the branches and tags a remote advertises, plus its HEAD.

func (r RemoteRefs) Resolve(name string) (Ref, error)

type RepoURL ¶

type RepoURL struct {
	Clone    string
	Scheme   string
	Host     string
	Path     string
	Provider string
	// Owner is the GitHub owner, the GitLab group path (nested groups joined
	// with "/"), or the Azure DevOps organization.
	Owner string
	// Project is the Azure DevOps project; empty elsewhere.
	Project string
	Name    string
	// Ref and Depth come from the ?ref= and ?depth= query parameters.
	Ref   string
	Depth *int
	User  string
}

RepoURL is a parsed repository URL. Clone is what git is given: the URL without query, fragment or password.

func ParseRepoURL(raw, providerHint string) (RepoURL, error)

func (u RepoURL) CacheKey() string

func (u RepoURL) FullName() string

func (u RepoURL) Redacted() string

func (u RepoURL) Short() string

type Repository ¶

type Repository struct {
	URL  RepoURL
	Auth Auth
	// Provider opens pull requests; nil or a generic git provider has none.
	Provider Provider
}

Repository is one remote repository with the credentials to reach it and, when it is hosted on a supported provider, that provider's API.

func NewRepository(options RepositoryOptions) (*Repository, error)

func (r *Repository) LsRemote(ctx context.Context) (RemoteRefs, error)

func (r *Repository) OpenPullRequest(ctx context.Context, request PullRequestRequest) (PullRequest, error)

func (r *Repository) Resolve(ctx context.Context, ref string) (Ref, error)

type RepositoryInfo ¶

type RepositoryInfo struct {
	Name          string
	FullName      string
	Namespace     string
	CloneURL      string
	SSHURL        string
	WebURL        string
	DefaultBranch string
	Private       bool
	Archived      bool
}

RepositoryInfo is one repository as the provider lists it.

type RepositoryOptions ¶

type RepositoryOptions struct {
	URL      string
	Auth     Auth
	Provider Provider
	// ProviderType is the URL parsing hint (models.ConnectionType*); it
	// defaults to Provider.Type().
	ProviderType string
}

RepositoryOptions configures NewRepository.

type Signature ¶

type Signature struct {
	Name  string
	Email string
}

Signature is a commit author or tag tagger.

func DefaultIdentity(ctx context.Context) (Signature, error)

type TLS ¶

type TLS struct {
	CA                 string
	Cert               string
	Key                string
	InsecureSkipVerify bool
}

TLS customizes HTTPS verification: an extra CA bundle (added to the system pool), a client certificate for mutual TLS, or no verification at all. InsecureSkipVerify also disables SSH host-key checking.

type TagOptions ¶

type TagOptions struct {
	Name    string
	Message string
	Tagger  Signature
}

TagOptions configures Worktree.CreateTag; an empty Message makes a lightweight tag.

type Worktree ¶

type Worktree struct {
	Dir string
	Ref Ref
	// contains filtered or unexported fields
}

Worktree is a leased checkout from a Cache. Release it when done.

func (w *Worktree) Commit(ctx context.Context, options CommitOptions) (string, error)

func (w *Worktree) CreateBranch(ctx context.Context, name string) error

func (w *Worktree) CreateTag(ctx context.Context, options TagOptions) error

func (w *Worktree) DeleteFile(path string) error

func (w *Worktree) Push(ctx context.Context, options PushOptions) error

func (w *Worktree) Release() error

func (w *Worktree) WriteFile(path string, content []byte) error