git

package
v0.1.74 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: Apache-2.0 Imports: 53 Imported by: 0

README

Git repository caches

Cache{Root: ...} stores fetched Git objects and leases working trees. Repositories opened with Azure DevOps, GitHub, or GitLab provider clients automatically probe existing complete mirrors before creating a new store. A confirmed common ancestor allows the new repository to reuse that store. Plain Git connections retain per-repository caching.

cache := &git.Cache{Root: cacheDirectory}
worktree, err := cache.Checkout(ctx, repository, git.CheckoutOptions{
    Ref: "main", Ephemeral: true,
})
if err != nil {
    return err
}
defer worktree.Release()

Root is the sharing boundary and must be a trusted local cache directory. The supplied repository provides its own credentials and hosting API. Discovery uses metadata-only REST requests; it never requires Git protocol v2. Unknown candidate commits are tried against cached roots. Authentication, rate limits, invalid responses, and network failures are returned to the caller.

Each logical repository records its physical owner in an atomic, versioned repository.json. Existing mirrors are adopted in place. Existing stores are never moved, merged, or deleted by discovery. Removing an owner directory while bindings reference it produces an explicit error. Maintenance visits physical mirrors once; active worktrees remain registered with Git and retain their commits.

Fetched refs, writable branches, and tags are isolated by repository. Worktree-created refs also include the lease identity. Push operations retain the requested remote branch/tag names, and annotated tags retain their logical tag names.

Independent clones

Pass the same cache to CloneOptions to fetch once into the cache and copy the requested history locally:

_, err := git.Clone(ctx, repository, git.CloneOptions{
    Dir: destination, Ref: "main", Cache: cache,
})
if err != nil {
    return err
}

The destination has its own objects, its origin names the requested repository, and it remains usable after the cache is removed. No persistent alternates are installed. Omitting Cache uses the ordinary remote clone path.

Depth limits standalone clone history. Shallow cache-assisted clones and provider-backed shallow checkouts use isolated depth-specific stores so they cannot truncate a shared complete mirror. Discovery timing is recorded in the existing Git timing collector; pack transfer bytes remain available through fetch progress observations.

Documentation

Overview

Package git is commons-db's git client: remote listing, checkouts into a shared cache, commits, tags and pushes, and the provider REST APIs (GitHub, GitLab, Azure DevOps) that open pull requests.

Layers

  • url.go parses a repository URL into provider coordinates (RepoURL).
  • remote.go lists remote refs with go-git (LsRemote) and resolves a ref name to a commit (RemoteRefs.Resolve).
  • clone.go, cache.go and worktree.go put a ref on disk with the git binary: a plain clone for shell checkouts, or a mirror plus leased worktrees.
  • change.go composes a worktree into a branch, commit, push and pull request (Cache.Apply), optionally cherry-picking commits onto the base first (cherrypick.go).
  • log.go reads the commits between two refs (Cache.Log, Cache.Compare) and one ref's path history with per-file changes (Cache.History) from the mirror; show.go reads a file at a commit (Cache.Show), with ErrPathNotFound for a path absent there; pullrequest.go opens a pull request between two existing branches (Repository.OpenPullRequest).
  • changes.go compares endpoint object IDs without loading bodies; blobs.go reads selected files in one batch; blame.go attributes supplied contents directly against an immutable commit in the bare mirror.
  • ignore.go lists tracked and unignored paths in a local checkout.
  • source.go prepares local working, commit and staged sources with their changed paths, isolating immutable sources from the original index and checkout.
  • provider*.go and rest.go talk to the hosting provider's REST API.
  • factory.go builds a Client from a hydrated models.Connection.

Why disk operations use the git binary

go-git is used for LsRemote only, against in-memory storage. Fetching with go-git breaks on servers that need multi_ack negotiation (Azure DevOps; see go-git plumbing/protocol/packp/srvresp.go, the multi_ack TODO), which the old client papered over by mutating the process-global transport.UnsupportedCapabilities. go-git v5 also has no linked worktrees. The git binary (>= 2.42, for bare supplied-content blame) handles both, and nothing in this package mutates go-git globals: TLS for LsRemote is passed per call.

Credential policy

Credentials reach the git binary only through its environment, never argv and never a config file on disk:

  • HTTP(S): GIT_CONFIG_COUNT sets a URL-scoped http.<url>.extraHeader with the Basic Authorization header, plus credential.helper="" so no helper is consulted or written to.
  • SSH: GIT_SSH_COMMAND points at a 0600 temporary key with strict known_hosts checking (disabled only by TLS.InsecureSkipVerify).
  • GIT_TERMINAL_PROMPT=0 so a rejected credential fails instead of prompting.

Repository URLs must not embed a password. Every revision argument is preceded by --end-of-options, and branch, tag and revision names are validated before they reach a command line.

Config isolation

Every command runs in an environment built by baseEnv, so the calling process's own git setup cannot steer it:

  • GIT_CONFIG_NOSYSTEM=1 and GIT_CONFIG_GLOBAL=/dev/null: neither the system nor the user's global config is read, so no url.insteadOf, credential helper or default identity leaks in.
  • core.hooksPath=/dev/null: no hook (pre-commit, pre-push, …) runs, from the user's config or from a repository template.
  • commit.gpgSign=false and tag.gpgSign=false: a commit or tag never waits on a signing key or agent the server does not have.
  • inherited GIT_DIR, GIT_WORK_TREE, GIT_CONFIG_*, GIT_SSH*, GIT_ASKPASS, GIT_AUTHOR_*, GIT_COMMITTER_* and GIT_TRACE* are dropped; the last keeps a traced Authorization header out of the stderr an error carries.

Commit and tag authors are therefore always explicit (Signature). DefaultIdentity is the one deliberate read of the global config: it returns the process's own user.name and user.email, for a caller that authors a commit as the server itself.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrSharedCacheUnsupported is returned when a repository's provider
	// cannot compare remote history, so its mirror is never shared.
	ErrSharedCacheUnsupported = errors.New("shared git cache is not supported for this repository")
	// ErrCacheBusy is returned when a cache action would remove a worktree a
	// Checkout has leased.
	ErrCacheBusy = errors.New("git cache entry is in use")
	// ErrCacheEntry is returned for a cache action on a key that does not
	// have the state the action needs (no mirror to evict, nothing to rebind).
	ErrCacheEntry = errors.New("invalid git cache entry for this action")
)
View Source
var (
	// ErrPullRequestsUnsupported is returned when the repository's provider
	// cannot open pull requests (plain git, or no provider).
	ErrPullRequestsUnsupported = errors.New("pull requests are not supported by this git provider")
	// ErrBranchExists is returned when a change would push to a branch that
	// already exists on the remote.
	ErrBranchExists = errors.New("branch already exists on the remote")
	// ErrTagExists is returned when a change would push a tag that already
	// exists on the remote.
	ErrTagExists = errors.New("tag already exists on the remote")
	// ErrBaseMoved is returned when a change pinned to a base commit
	// (ChangeRequest.BaseSHA) finds the base branch at a different commit.
	ErrBaseMoved = errors.New("change base moved off the expected commit")
	// ErrUnrelatedHistories is returned when two commits share no ancestor,
	// e.g. branches of repositories that are not forks of one another.
	ErrUnrelatedHistories = errors.New("the commits share no history")
)
View Source
var (
	ErrInvalidSource     = errors.New("invalid source request")
	ErrRevisionNotFound  = errors.New("revision does not resolve to one commit")
	ErrUnmergedIndex     = errors.New("unmerged index")
	ErrSourceChanged     = errors.New("source changed while capturing")
	ErrUnsupportedSource = errors.New("unsupported source")
)
View Source
var ErrNoCommitView = errors.New("no web commit view")
View Source
var ErrNoFileView = errors.New("no web file view")

ErrNoFileView is returned by FileURL for a repository whose host has no known web file view: a generic git host or a local repository.

View Source
var ErrNoIdentity = errors.New("no git user.name/user.email configured")

ErrNoIdentity marks a process whose global git config lacks user.name or user.email.

View Source
var ErrNotRepository = errors.New("not a git repository")
View Source
var ErrPathNotFound = errors.New("path not found at commit")

ErrPathNotFound is returned by Cache.Show when the path does not exist at the commit (never added, or deleted by then).

View Source
var ErrPipelinesUnsupported = errors.New("pipelines are not supported by this git provider")

Functions

func ActivityMentions added in v0.1.62

func ActivityMentions(body string) []string

ActivityMentions returns canonical mention identities in prose order, excluding code and email addresses.

func CherryPickLocal added in v0.1.74

func CherryPickLocal(ctx context.Context, options LocalCherryPickOptions) (string, error)

CherryPickLocal replays the commits without a worktree or index: each one is merged with git merge-tree and written with git commit-tree into Dir's own object store, keeping its message, author and author date, under the caller's git configuration (committer identity included). It returns the replayed tip; no ref is created or moved. A conflict is *CherryPickConflictError and a commit already on the tip *CherryPickEmptyError.

func FreshRefs added in v0.1.72

func FreshRefs(ctx context.Context) bool
func Head(ctx context.Context, directory string) (string, error)

Head returns the full commit ID of a local repository's HEAD.

func IndexFiles added in v0.1.72

func IndexFiles(ctx context.Context, options IndexFilesOptions) ([]string, error)

func ObjectID added in v0.1.64

func ObjectID(entry fs.DirEntry) (string, bool)

ObjectID is the Git object ID (blob or tree) of an entry a Tree listed.

func PushLocal added in v0.1.74

func PushLocal(ctx context.Context, options LocalPushOptions) error

PushLocal pushes the commit with the caller's git configuration, so the remote's own URL and credential helper apply. It never forces.

func ReadLocalFiles added in v0.1.64

func ReadLocalFiles(ctx context.Context, options LocalFilesOptions) (map[string]LocalFile, error)

ReadLocalFiles lists the requested entries Commit has in one spawn and reads each blob among them in one more.

func Redact

func Redact(text string) string

Redact removes user info from every URL in text, e.g. git error output.

func ValidateBranchName

func ValidateBranchName(name string) error

ValidateBranchName applies the rules of `git check-ref-format --branch` without spawning git, so a branch name from a request is refused before it reaches `git branch`, `git push` or a refspec.

func ValidateRevision

func ValidateRevision(rev string) error

ValidateRevision rejects a revision that git could read as something other than a revision before it is ever placed on a git command line. A leading "-" would be parsed as an option (`--upload-pack=…` runs a program), and whitespace or a control character means the value was not one revision to begin with. Revision syntax itself is left to git. Callers still put `--end-of-options` ahead of the value.

func ValidateTagName

func ValidateTagName(name string) error

ValidateTagName applies the same ref-format rules to a tag name.

func WithFetchObserver added in v0.1.64

func WithFetchObserver(ctx context.Context, observer FetchObserver) context.Context

WithFetchObserver makes every fetch run under ctx (clones, cache checkouts, reads that fetch a missing commit) report its progress to observer.

func WithFreshRefs added in v0.1.72

func WithFreshRefs(ctx context.Context) context.Context

func WithReadCache added in v0.1.72

func WithReadCache(ctx context.Context, cache *readcache.Cache) context.Context

WithReadCache supplies a shared adapter without retaining the request context.

func WithReadObserver added in v0.1.72

func WithReadObserver(ctx context.Context, observer ReadObserver) context.Context

func WithSecurityNamespace added in v0.1.72

func WithSecurityNamespace(ctx context.Context, namespace string) context.Context

WithSecurityNamespace isolates reads for callers sharing transport credentials.

Types

type APIError

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

APIError is a non-2xx provider API response.

func (*APIError) Error

func (e *APIError) Error() string

type AncestorsOptions added in v0.1.64

type AncestorsOptions struct {
	Repository *Repository
	Directory  string
	Head       string
	Max        int
}

AncestorsOptions names a head in one cached remote Repository or one existing local Directory (working or bare, read in place, never fetched). Max bounds how many commits are listed and is required.

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 (Auth) Validate

func (a Auth) Validate() error

Validate rejects ambiguous or malformed credentials.

type BlameAuthor added in v0.1.62

type BlameAuthor struct {
	Name  string `json:"name"`
	Email string `json:"email"`
}

type BlameCommit added in v0.1.62

type BlameCommit struct {
	SHA     string      `json:"sha"`
	URL     string      `json:"url,omitempty"`
	Author  BlameAuthor `json:"author"`
	Date    time.Time   `json:"date"`
	Subject string      `json:"subject"`
}

type BlameLine added in v0.1.62

type BlameLine struct {
	Line         int          `json:"line"`
	OriginalLine int          `json:"originalLine"`
	Path         string       `json:"path"`
	Content      string       `json:"content"`
	Commit       *BlameCommit `json:"commit"`
}

BlameLine has no Commit when its content is outside the selected revision.

type BlameOptions added in v0.1.62

type BlameOptions struct {
	SHA      string
	Path     string
	Contents []byte
}

BlameOptions supplies the displayed contents of a file at an immutable commit.

type BlobRequest added in v0.1.62

type BlobRequest struct {
	SHA  string
	Path string
}

BlobRequest identifies a literal file path at a full commit SHA.

type BlobResult added in v0.1.62

type BlobResult struct {
	Content []byte
	Object  string
	Present bool
}

BlobResult distinguishes absent paths from present files with empty content.

type Cache

type Cache struct {
	Root string
}

Cache leases worktrees from cached bare repositories. Provider-backed repositories with common history can share a physical mirror:

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

mirror.lock is held shared by reads and exclusively by fetches, pin writes, Maintain and worktree bookkeeping; a pin file's mtime is when a read last used that commit (see Maintain). Each worktree is leased exclusively until Release, so concurrent checkouts of different refs proceed while a second checkout of the same ref waits.

func (*Cache) Ancestors added in v0.1.64

func (c *Cache) Ancestors(ctx context.Context, options AncestorsOptions) ([]string, error)

Ancestors lists Head and its ancestors nearest first (rev-list order), at most Max of them, so a caller ranks stored commits by distance in one spawn (a Head that is not a full commit ID is resolved first). A cached repository fetches Head with its history.

func (*Cache) Apply

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

Apply runs a ChangeRequest. Every check that can fail without touching the remote runs first: a provider without pull requests returns ErrPullRequestsUnsupported and an existing remote branch ErrBranchExists, before anything is pushed.

func (*Cache) Blame added in v0.1.62

func (c *Cache) Blame(ctx context.Context, repo *Repository, options BlameOptions) ([]BlameLine, error)

func (*Cache) Changes added in v0.1.62

func (c *Cache) Changes(ctx context.Context, options ChangesOptions) ([]Change, error)

Changes compares endpoint trees without reading file bodies. Without Renames, a rename is a deletion and an addition.

func (*Cache) Checkout

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

Checkout leases a worktree at ref. A commit already in the mirror is not fetched again.

func (*Cache) Compare

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

func (*Cache) Evict added in v0.1.72

func (c *Cache) Evict(ctx context.Context, options EvictOptions) (result EvictResult, err error)

Evict deletes a mirror with its pins and worktrees, and the bindings and worktrees of the repositories bound to it. It waits for reads and fetches in flight, and fails with ErrCacheBusy while one of those worktrees is leased. A Tree opened before Evict fails on its next read.

func (*Cache) Files added in v0.1.62

func (c *Cache) Files(ctx context.Context, repo *Repository, sha string) ([]string, error)

func (*Cache) History added in v0.1.60

func (c *Cache) History(ctx context.Context, repo *Repository, ref string, options HistoryOptions) ([]Commit, error)

func (*Cache) Inventory added in v0.1.72

func (c *Cache) Inventory(ctx context.Context) ([]CacheEntry, error)

Inventory describes every cache entry under Root without taking any lock a read or fetch waits on, sorted by key.

func (*Cache) LocalFile added in v0.1.72

func (c *Cache) LocalFile(ctx context.Context, options LocalFileOptions) (LocalFileInfo, error)

LocalFile reads live path status and caches committed provenance independently.

func (*Cache) Log

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

func (*Cache) Maintain added in v0.1.64

func (c *Cache) Maintain(ctx context.Context, options MaintainOptions) error

Maintain expires, in every mirror under Root, the commit pins no read has used for PinTTL, then runs git's gc task, each mirror under its exclusive lock. A pin's last use is its pin file's mtime, refreshed by every read (the ref itself points at the commit, whose date says nothing of use); a pin ref without a pin file has not been read since pin files existed and expires. A Tree keeps no pin fresh while open, so PinTTL must exceed the longest a Tree stays open.

func (*Cache) MergeBase added in v0.1.62

func (c *Cache) MergeBase(ctx context.Context, repo *Repository, options MergeBaseOptions) (string, error)

func (*Cache) OpenTree added in v0.1.62

func (c *Cache) OpenTree(ctx context.Context, options TreeOptions) (result *Tree, err error)

OpenTree captures the revision without writing source files or leasing a worktree. Close releases its reader slot and any private local Git metadata.

func (*Cache) PrepareSource added in v0.1.62

func (c *Cache) PrepareSource(ctx context.Context, options SourceOptions) (source *PreparedSource, err error)

PrepareSource captures a local source and its changes. Commit and staged sources contain raw blob bytes.

func (*Cache) ReadBlobs added in v0.1.62

func (c *Cache) ReadBlobs(ctx context.Context, repo *Repository, requests []BlobRequest) ([]BlobResult, error)

ReadBlobs reads files in request order using one native Git object batch. Directories, invalid revisions and command failures return errors.

func (*Cache) Rebind added in v0.1.72

func (c *Cache) Rebind(ctx context.Context, repo *Repository, options RebindOptions) (result RebindResult, err error)

Rebind moves a repository bound to another repository's mirror onto a different mirror: it fetches the repository's remote HEAD into the new owner, publishes the binding, then removes the repository's worktrees and recorded refs from the previous owner. It fails with ErrCacheBusy while one of the repository's worktrees is leased, and with ErrUnrelatedHistories for an Owner sharing no history with it.

func (*Cache) SharedOwners added in v0.1.72

func (c *Cache) SharedOwners(ctx context.Context, repo *Repository) ([]SharedOwner, error)

SharedOwners ranks the cached mirrors, other than repo's own, that share history with repo's remote HEAD: the most shared commits (the fewest left to fetch) first, then the most recently modified mirror. Rebind without an Owner binds repo to the first.

func (*Cache) Show added in v0.1.60

func (c *Cache) Show(ctx context.Context, repo *Repository, sha, path string) ([]byte, error)

Show returns the bytes of the file at path in commit sha, read from the bare mirror; a commit the mirror lacks is fetched first. sha must be a full 40-character SHA. path is matched literally (no pathspec magic); a path that names a directory is an error.

type CacheEntry added in v0.1.72

type CacheEntry struct {
	Key        string          `json:"key"`
	Repository string          `json:"repository,omitempty"`
	Owner      string          `json:"owner"`
	BoundAt    *time.Time      `json:"boundAt,omitempty"`
	Dependents []string        `json:"dependents,omitempty"`
	Mirror     *MirrorState    `json:"mirror,omitempty"`
	Commits    []CachedCommit  `json:"commits,omitempty"`
	Worktrees  []WorktreeState `json:"worktrees,omitempty"`
	Error      string          `json:"error,omitempty"`
}

CacheEntry is one repository's directory under Cache.Root. Owner is the cache key whose mirror holds its objects (Key itself for a mirror it owns); Error reports an entry that could not be read, with the rest left empty.

type CachedCommit added in v0.1.72

type CachedCommit struct {
	Ref       string    `json:"ref"`
	SHA       string    `json:"sha"`
	Committed time.Time `json:"committed"`
}

CachedCommit is a commit recorded for an entry in its owner's mirror: Ref is heads/<branch> or commits/<sha>.

type Change added in v0.1.62

type Change struct {
	Path      string
	OldPath   string
	Status    FileStatus
	OldObject string
	NewObject string
	OldMode   string
	NewMode   string
}

Change describes a literal path's object and mode changes. Missing objects have empty IDs; mode-only changes keep equal OldObject and NewObject IDs. OldPath is set for a FileRenamed change only.

type ChangeRequest

type ChangeRequest struct {
	Base               string
	BaseSHA            string
	Branch             string
	Message            string
	Author             Signature
	Source             *Repository
	Head               string
	Rebase             string
	Pick               PickStrategy
	Squash             bool
	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.

Head, instead of CherryPick and Files, points Branch at that full commit SHA as is: a pull request of it merges its history into Base. It must share history with Base (ErrUnrelatedHistories) and not already be on it.

Source is the repository the CherryPick, Head or Rebase commits are fetched from when it is not the changed one, e.g. a fork; nil is the changed repository.

Pick is how CherryPick commits land: PickCherryPick (the default) runs git cherry-pick -x and needs history shared with Base; PickReplay applies each commit's patch as a new commit (git format-patch | git am --3way) keeping its message, author and date, and needs no shared history. Squash then folds the landed commits into one: their messages joined in order, the first commit's author and date, a Co-authored-by trailer per other author, then Trailers.

Rebase, instead of CherryPick, Files and Head, rebases the commits of that full SHA which Base lacks onto Base with git rebase: linear, each commit's message, author and date kept, so it takes no Trailers. It must share history with Base (ErrUnrelatedHistories).

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 ChangesOptions added in v0.1.62

type ChangesOptions struct {
	Repository *Repository
	Directory  string
	Base       string
	Head       string
	Paths      []string
	Renames    bool
}

ChangesOptions selects the two endpoint trees to compare, from one cached remote Repository or one existing local Directory (working or bare, read through the same private scratch as OpenTree, never fetched). Paths (matched literally, never as globs) keeps only changes under them; Renames detects renames (-M), reporting each once as FileRenamed with its OldPath.

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 (*CherryPickConflictError) Error

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 (*CherryPickEmptyError) Error

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

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

FromConnection builds a Client from a hydrated connection (URL, username, password and certificate already resolved). Type git uses Username/Password, with Certificate as the SSH private key, and its URL is the repository. github, gitlab and azure_devops carry a PAT in Password and the API URL in URL; the namespace comes from Properties organization, group or project respectively.

func (*Client) CacheKey added in v0.1.72

func (c *Client) CacheKey() string

func (*Client) Repository

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

Repository opens rawURL with the connection's credentials and provider, refusing a repository outside the connection's host and organization.

func (*Client) Scope added in v0.1.72

func (c *Client) Scope() ConnectionScope

Scope is what the connection may open (ScopeOf).

type ClientOptions added in v0.1.62

type ClientOptions struct {
	TransportPool     *commonshttp.TransportPool
	SecurityNamespace string
	ReadCache         *readcache.Cache
}

ClientOptions shares transport connections while keeping middleware per client.

type CloneOptions

type CloneOptions struct {
	// Cache supplies an optional object cache; the clone remains independent.
	Cache *Cache
	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
	Status   map[string]FileStatus
	Renames  []Rename
}

Commit is one commit as Cache.Log or Cache.History reads it. Files are the paths it changed against its first parent (a rename lists its new path); a merge commit (len(Parents) > 1) lists none. Status and Renames are filled by History only: how each of Files changed, and which renamed from what.

func (Commit) IsMerge

func (c Commit) IsMerge() bool

IsMerge reports whether the commit has more than one parent.

type CommitOptions

type CommitOptions struct {
	Message string
	Author  Signature
}

CommitOptions configures Worktree.Commit.

type CommitState added in v0.1.60

type CommitState string

CommitState is a provider-neutral commit status state.

const (
	CommitStatePending CommitState = "pending"
	CommitStateSuccess CommitState = "success"
	CommitStateFailure CommitState = "failure"
	CommitStateError   CommitState = "error"
)

type CommitStatus added in v0.1.60

type CommitStatus struct {
	State       CommitState
	Context     string
	Description string
	TargetURL   string
}

CommitStatus is a status reported on a commit. Context names the check (statuses with the same context replace each other); TargetURL links to its details.

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 ConnectionScope added in v0.1.72

type ConnectionScope struct {
	Type string
	// Repository is the one repository a git connection names; nil for a
	// provider connection.
	Repository *RepoURL
	// API is the base URL a provider connection calls; nil for a git
	// connection.
	API *url.URL
	// Namespace is the GitHub organization, GitLab group or Azure DevOps
	// project the connection is limited to; empty for none.
	Namespace string
}

ConnectionScope is what a git connection may open, read from the connection alone: no secret is hydrated and no client is built, so a catalog can be matched against a checkout's remote. Client.Repository refuses exactly the repositories Owns refuses.

func ScopeOf added in v0.1.72

func ScopeOf(conn models.Connection) (ConnectionScope, error)

ScopeOf reads the scope of conn. Type git takes its URL as the repository; github, gitlab and azure_devops take it as the API (public GitHub when empty) and the namespace from Properties organization, group or project.

func (ConnectionScope) Owns added in v0.1.72

func (s ConnectionScope) Owns(repo RepoURL) error

Owns refuses a repository outside the connection's host and namespace, or one reached over http when the connection is configured over https (its credentials would travel unencrypted). A git connection owns any repository on its host; SameRepository tells whether it is the one it names.

func (ConnectionScope) RepositoryName added in v0.1.72

func (s ConnectionScope) RepositoryName(repo RepoURL) string

RepositoryName is the name a provider connection lists repo by (RepositoryInfo.FullName, what browse.FindRepository resolves): owner/name on GitHub and GitLab, project/name on Azure DevOps, whose organization the connection fixes. A git connection pins one repository and names none.

type DirtyStats

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

func (DirtyStats) Clean

func (s DirtyStats) Clean() bool

type DiscoverOptions added in v0.1.72

type DiscoverOptions struct{ Path string }

type Discovery added in v0.1.72

type Discovery struct {
	Root            string
	GitDirectory    string
	CommonDirectory string
	Bare            bool
}

func Discover added in v0.1.72

func Discover(ctx context.Context, options DiscoverOptions) (Discovery, error)

Discover locates a repository without resolving a revision, including unborn checkouts.

type EvictOptions added in v0.1.72

type EvictOptions struct {
	Owner string
}

EvictOptions configures Cache.Evict: Owner is the cache key of a mirror.

type EvictResult added in v0.1.72

type EvictResult struct {
	Owner      string   `json:"owner"`
	Dependents []string `json:"dependents,omitempty"`
}

EvictResult names the evicted mirror and the repositories that were bound to it; each clones again, into the best remaining owner, on its next read.

type FetchObserver added in v0.1.64

type FetchObserver func(context.Context, FetchProgress)

FetchObserver receives every FetchProgress of the fetches made under a context. Fetches of different repositories may report concurrently.

type FetchProgress added in v0.1.64

type FetchProgress struct {
	ID         string
	Repository string
	Ref        string
	// Mirror is the cache key of the shared mirror the fetch writes into when
	// another repository owns it, and MirrorRepository that owner's recorded
	// repository (empty when unrecorded). Both are empty for the repository's
	// own mirror and for a clone.
	Mirror           string
	MirrorRepository string
	// Phase is git's phase label: "Enumerating objects", "Counting objects",
	// "Compressing objects" (Remote, on the server), "Receiving objects",
	// "Resolving deltas".
	Phase          string
	Remote         bool
	Percent        int
	Current        int64
	Total          int64 // 0 when git reports no bound
	Transferred    string
	Rate           string
	Bytes          int64
	BytesPerSecond float64
	PhaseDone      bool
	Done           bool
	Err            error
}

FetchProgress is one update of a fetch, as git's own progress meter shows it ("Receiving objects: 45% (450/1000), 12.00 MiB | 3.00 MiB/s"). Repository (redacted) and Ref identify the fetch; the last update of every fetch has Done set, with Err when it failed.

type FileChange

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

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

type FileCommit added in v0.1.72

type FileCommit struct {
	SHA         string
	CommittedAt time.Time
	Present     bool
}

type FileStatus added in v0.1.60

type FileStatus string

FileStatus is git's --name-status letter for one changed path.

const (
	FileAdded       FileStatus = "A"
	FileModified    FileStatus = "M"
	FileDeleted     FileStatus = "D"
	FileRenamed     FileStatus = "R"
	FileCopied      FileStatus = "C"
	FileTypeChanged FileStatus = "T"
)

type Fingerprint added in v0.1.62

type Fingerprint struct {
	Root string
	SHA  string
}

func WorktreeFingerprint added in v0.1.62

func WorktreeFingerprint(ctx context.Context, directory string) (Fingerprint, error)

WorktreeFingerprint hashes HEAD, refs and Git's changed paths with their modification times, sizes and modes. It stats dirty files without reading their contents; ignored files are excluded.

type HistoryDetail added in v0.1.62

type HistoryDetail string

HistoryDetail controls the file metadata included with each commit.

const (
	HistoryStatus   HistoryDetail = ""
	HistoryMetadata HistoryDetail = "metadata"
	HistoryNames    HistoryDetail = "names"
)

type HistoryOptions added in v0.1.60

type HistoryOptions struct {
	Detail HistoryDetail
	Paths  []string
	Follow bool
	Limit  int
	Since  string
	Offset int
}

HistoryOptions configures Cache.History. Paths (matched literally, never as globs) keeps only the commits that touch them; Follow continues one path's history past its renames (git log --follow, so exactly one path); Limit > 0 keeps the newest Limit commits; Since is a git date (--since) bounding how far back to read. Detail controls file metadata; its default detects renames.

type IndexFilesOptions added in v0.1.72

type IndexFilesOptions struct {
	Directory        string
	IncludeUntracked bool
}

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 ListPullRequestsOptions added in v0.1.60

type ListPullRequestsOptions struct {
	// Base is the branch the pull requests merge into; empty matches any.
	Base string
	// Head is the branch the pull requests merge from; empty matches any.
	Head string
	// State is the state to list; the zero value lists open pull requests.
	State PullRequestState
	// Limit caps how many pull requests are returned, following pages until
	// it is reached; <= 0 means 100.
	Limit int
}

ListPullRequestsOptions filters ListPullRequests.

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 LocalCherryPickOptions added in v0.1.74

type LocalCherryPickOptions struct {
	Dir        string
	Base       string
	CherryPick []string
	Mainline   int
}

LocalCherryPickOptions replays CherryPick (full SHAs), in order, onto Base (any revision) inside the local repository at Dir. Mainline is the 1-based parent a merge commit is replayed against.

type LocalFile added in v0.1.64

type LocalFile struct {
	Mode    string
	Type    string
	Content []byte
}

LocalFile is one committed tree entry; Content is read for a blob only.

type LocalFileInfo added in v0.1.72

type LocalFileInfo struct {
	Commit FileCommit
	Dirty  bool
}

type LocalFileOptions added in v0.1.72

type LocalFileOptions struct {
	Directory string
	Revision  string
	Path      string
}

type LocalFilesOptions added in v0.1.64

type LocalFilesOptions struct {
	Root   string
	Commit string
	Files  []string
}

LocalFilesOptions names root-relative Files (matched literally) to read at Commit of the local repository at Root.

type LocalPushOptions added in v0.1.74

type LocalPushOptions struct {
	Dir    string
	Remote string
	Commit string
	Branch string
}

LocalPushOptions pushes Commit (a full SHA) of the local repository at Dir to Branch of the configured Remote.

type LocalRevision added in v0.1.64

type LocalRevision struct {
	Root   string
	Bare   bool
	Prefix string
	Commit string
}

LocalRevision is where Directory sits in its repository: Root is the work tree (a bare repository's git directory), Prefix the slash-separated path of Directory below it ("" at the root or in a bare repository), Commit the revision's full commit ID. Paths are physical: git reports them with symlinks resolved.

func ResolveLocalRevision added in v0.1.64

func ResolveLocalRevision(ctx context.Context, options LocalRevisionOptions) (LocalRevision, error)

ResolveLocalRevision locates Directory in its repository and resolves Revision there, outside any cache, in two spawns.

type LocalRevisionOptions added in v0.1.64

type LocalRevisionOptions struct {
	Directory string
	Revision  string
}

LocalRevisionOptions names a revision of the existing local repository holding Directory.

type LogOptions

type LogOptions struct {
	Base     string
	Head     string
	Limit    int
	Paths    []string
	HeadFrom *Repository
}

LogOptions configures Cache.Log. Limit > 0 keeps only the newest Limit commits; Paths (matched literally, never as globs) keeps only the commits that touch them. HeadFrom, when set, is the repository head is read from (e.g. a fork of the logged repository): it resolves and is fetched there, into the logged repository's mirror. A head sharing no history with base lists every commit whose patch base lacks; MergeBase tells the two apart.

type MaintainOptions added in v0.1.64

type MaintainOptions struct {
	PinTTL time.Duration
	Owners []string
}

MaintainOptions configures Cache.Maintain. PinTTL is how long a commit pin survives without a read using it. Owners limits maintenance to those mirrors (cache keys owning a mirror); empty maintains every mirror.

type MergeBaseOptions added in v0.1.62

type MergeBaseOptions struct {
	Base     string
	Head     string
	HeadFrom *Repository
}

MergeBaseOptions configures Cache.MergeBase. HeadFrom is the repository Head is read from (e.g. a fork); nil is the base's own.

type Metadata

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

func Inspect

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

Inspect reads compact provenance of the checkout at dir. Hints preserve the user's requested URL/ref for detached cache worktrees, while every value read from git describes the exact checked-out tree.

type MirrorState added in v0.1.72

type MirrorState struct {
	SizeBytes int64      `json:"sizeBytes"`
	Objects   int64      `json:"objects"`
	Packs     int64      `json:"packs"`
	Shallow   bool       `json:"shallow"`
	Pins      int        `json:"pins"`
	LastUsed  *time.Time `json:"lastUsed,omitempty"`
	OldestUse *time.Time `json:"oldestUse,omitempty"`
	Locked    bool       `json:"locked"`
}

MirrorState describes a mirror an entry owns. Locked is true while a fetch, pin write or maintenance holds the mirror exclusively; LastUsed and OldestUse are the newest and oldest pin uses.

type Page added in v0.1.62

type Page[T any] struct {
	Items      []T    `json:"items"`
	NextCursor string `json:"nextCursor,omitempty"`
}

type PathVisibility added in v0.1.72

type PathVisibility struct {
	Path    string `json:"path"`
	Visible bool   `json:"visible"`
	Rule    string `json:"rule,omitempty"`
}

func CheckVisibility added in v0.1.72

func CheckVisibility(ctx context.Context, options VisibilityOptions) ([]PathVisibility, error)

CheckVisibility checks only supplied paths. Overrides use Git-style patterns, relative to Directory, in order after the checkout's native ignore rules.

type PickStrategy added in v0.1.62

type PickStrategy string

PickStrategy is how ChangeRequest.CherryPick commits land on the branch.

const (
	// PickCherryPick runs git cherry-pick -x: it records the origin commit and
	// needs history shared with the base. It is the zero value's meaning.
	PickCherryPick PickStrategy = "cherry-pick"
	// PickReplay applies each commit's patch as a new commit (git format-patch
	// | git am --3way), keeping its message, author and date; it needs no
	// shared history and refuses merge commits.
	PickReplay PickStrategy = "replay"
)

type Pipeline added in v0.1.62

type Pipeline struct {
	ID    string `json:"id"`
	Name  string `json:"name"`
	Path  string `json:"path,omitempty"`
	URL   string `json:"url,omitempty"`
	State string `json:"state,omitempty"`
}

type PipelineExecution added in v0.1.62

type PipelineExecution struct {
	ID        string    `json:"id"`
	Pipeline  string    `json:"pipeline"`
	Number    string    `json:"number"`
	Name      string    `json:"name"`
	Attempt   int       `json:"attempt,omitempty"`
	Branch    string    `json:"branch"`
	SHA       string    `json:"sha"`
	Status    string    `json:"status"`
	Result    string    `json:"result,omitempty"`
	Author    string    `json:"author,omitempty"`
	CreatedAt time.Time `json:"createdAt"`
	URL       string    `json:"url,omitempty"`
}

type PipelineOptions added in v0.1.62

type PipelineOptions struct {
	Repository RepoURL
	Pipeline   string
	Branch     string
	Cursor     string
	Limit      int
}

type PipelineProvider added in v0.1.62

type PipelineProvider interface {
	ListPipelines(context.Context, PipelineOptions) (Page[Pipeline], error)
	ListPipelineExecutions(context.Context, PipelineOptions) (Page[PipelineExecution], error)
}

func PipelineAPI added in v0.1.62

func PipelineAPI(provider Provider) (PipelineProvider, error)

type PreparedSource added in v0.1.62

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

PreparedSource owns an isolated tree, or borrows the live working tree for SourceWorktree.

func (*PreparedSource) Changes added in v0.1.62

func (s *PreparedSource) Changes() []SourceChange

Changes returns an independent, path-sorted selection, including deletions. An empty selection is non-nil.

func (*PreparedSource) Info added in v0.1.62

func (s *PreparedSource) Info() SourceInfo

func (*PreparedSource) Release added in v0.1.62

func (s *PreparedSource) Release() error

Release removes only this source's owned resources, independently of the request context.

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)
	ListPullRequestActivity(ctx context.Context, repo RepoURL, number int) ([]PullRequestActivity, error)
	ListPullRequests(ctx context.Context, repo RepoURL, options ListPullRequestsOptions) ([]PullRequest, error)
	ClosePullRequest(ctx context.Context, repo RepoURL, number int) error
	// SetCommitStatus reports a commit status (a check) on sha.
	SetCommitStatus(ctx context.Context, repo RepoURL, sha string, status CommitStatus) error
	// CommentPullRequest adds a comment to the pull request and returns the
	// comment's web URL.
	CommentPullRequest(ctx context.Context, repo RepoURL, number int, body string) (string, 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
	Author    string
	Body      string
	CreatedAt time.Time
	// HeadSHA is the commit the head branch points at.
	HeadSHA string
	// HeadRepository is the full name (as RepositoryInfo.FullName) of the
	// repository the head branch lives in: the fork for a fork pull request,
	// the pull request's own repository otherwise. Empty only when the
	// provider no longer knows it (GitHub: a deleted fork).
	HeadRepository string
	Metadata       *PullRequestMetadata
}

PullRequest is an opened pull (or merge) request.

type PullRequestActivity added in v0.1.60

type PullRequestActivity struct {
	Kind      PullRequestActivityKind `json:"kind"`
	Author    string                  `json:"author"`
	Body      string                  `json:"body"`
	CreatedAt time.Time               `json:"createdAt"`
	URL       string                  `json:"url,omitempty"`
	ID        string                  `json:"id,omitempty"`
	Action    string                  `json:"action,omitempty"`
	UpdatedAt time.Time               `json:"updatedAt,omitempty"`
	Mentions  []string                `json:"mentions,omitempty"`
}

type PullRequestActivityKind added in v0.1.60

type PullRequestActivityKind string
const (
	PullRequestComment PullRequestActivityKind = "comment"
	PullRequestHistory PullRequestActivityKind = "history"
)

type PullRequestCheck added in v0.1.62

type PullRequestCheck struct {
	Name     string `json:"name"`
	State    string `json:"state"`
	URL      string `json:"url,omitempty"`
	Required bool   `json:"required,omitempty"`
}

type PullRequestChecksReader added in v0.1.62

type PullRequestChecksReader interface {
	PullRequestChecks(context.Context, RepoURL, PullRequest) ([]PullRequestCheck, error)
}

type PullRequestMetadata added in v0.1.62

type PullRequestMetadata struct {
	Author          string             `json:"author"`
	AuthorAvatarURL string             `json:"authorAvatarUrl,omitempty"`
	CreatedAt       time.Time          `json:"createdAt"`
	BaseSHA         string             `json:"baseSha,omitempty"`
	HeadSHA         string             `json:"headSha"`
	HeadBranch      string             `json:"headBranch"`
	BaseBranch      string             `json:"baseBranch"`
	HeadBranchURL   string             `json:"headBranchUrl,omitempty"`
	HeadCommitURL   string             `json:"headCommitUrl,omitempty"`
	BaseBranchURL   string             `json:"baseBranchUrl,omitempty"`
	BaseCommitURL   string             `json:"baseCommitUrl,omitempty"`
	Mergeability    string             `json:"mergeability"`
	MergeReason     string             `json:"mergeReason,omitempty"`
	Draft           bool               `json:"draft,omitempty"`
	Checks          []PullRequestCheck `json:"checks"`
}

func ReadPullRequestMetadata added in v0.1.62

func ReadPullRequestMetadata(ctx context.Context, provider PullRequestReader, repo RepoURL, options PullRequestMetadataOptions) (*PullRequestMetadata, error)

type PullRequestMetadataOptions added in v0.1.62

type PullRequestMetadataOptions struct {
	Number  int
	BaseSHA string
	// Listed is the pull request a ListPullRequests returned, read instead of
	// a GetPullRequest. GitHub's listing has no mergeability, so GitHub still
	// reads the pull request.
	Listed *PullRequest
	// SkipChecks reads no checks and leaves Checks nil.
	SkipChecks bool
}

type PullRequestPolicy added in v0.1.60

type PullRequestPolicy struct {
	ID                   int
	Name                 string
	Status               string
	Required             bool
	BuildID              int
	URL                  string
	MinimumApproverCount int
}

type PullRequestReader added in v0.1.64

type PullRequestReader interface {
	Type() string
	GetPullRequest(ctx context.Context, repo RepoURL, number int) (PullRequest, error)
}

PullRequestReader is the part of a Provider pull request metadata reads.

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 PullRequestReview added in v0.1.60

type PullRequestReview struct {
	Policies  []PullRequestPolicy
	Reviewers []PullRequestReviewer
}

type PullRequestReviewReader added in v0.1.60

type PullRequestReviewReader interface {
	PullRequestReview(ctx context.Context, repo RepoURL, number int) (PullRequestReview, error)
}

PullRequestReviewReader reads a host's current review and merge requirements.

type PullRequestReviewer added in v0.1.60

type PullRequestReviewer struct {
	ID       string
	Name     string
	Required bool
	Vote     int
}

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
	Commit        string
	Tags          []string
	Force         bool
	ExpectedSHA   string
	ServerOptions []string
	// contains filtered or unexported fields
}

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). Commit, a full SHA, is pushed in place of the local Branch, which then only names the remote branch.

type ReadObserver added in v0.1.72

type ReadObserver func(context.Context, ReadProgress)

type ReadProgress added in v0.1.72

type ReadProgress struct {
	ID, Repository, Ref   string
	Current, Total, Bytes int64
	BytesPerSecond        float64
	Done                  bool
	Err                   error
}

ReadProgress reports measured object IO. Total is zero for an open-ended tree reader.

type RebindOptions added in v0.1.72

type RebindOptions struct {
	Owner string
}

RebindOptions configures Cache.Rebind: Owner is the cache key of the mirror to bind to; empty binds to the best of SharedOwners (or a dedicated mirror when none shares history).

type RebindResult added in v0.1.72

type RebindResult struct {
	Key      string `json:"key"`
	Previous string `json:"previous"`
	Owner    string `json:"owner"`
}

RebindResult is the repository's cache key with its previous and new owner.

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

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

Clone puts ref of repo into Dir: init (or reuse an existing checkout), fetch exactly that ref, and check it out (on a local branch of the same name for branches, detached otherwise). It returns the ref with SHA set to the commit checked out.

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 RemoteHistoryProvider added in v0.1.69

type RemoteHistoryProvider interface {
	RemoteMergeBase(context.Context, RemoteMergeBaseOptions) (string, error)
}

RemoteHistoryProvider discovers shared history without downloading Git objects.

type RemoteMergeBaseOptions added in v0.1.69

type RemoteMergeBaseOptions struct {
	Repository RepoURL
	BaseSHA    string
	HeadSHA    string
}

RemoteMergeBaseOptions selects two immutable commits in the target provider.

type RemoteRefs

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

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

func (RemoteRefs) Resolve

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

Resolve finds name as, in order: a full ref, HEAD, a branch, a tag, then a 40-char SHA. A branch takes precedence over a same-named tag. An empty name is HEAD. Short SHAs are refused: they cannot be fetched by name.

type Rename added in v0.1.60

type Rename struct {
	From string
	To   string
}

Rename is a path a commit moved From one name To another.

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

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

ParseRepoURL parses an HTTP(S), SSH, scp-style, git://, file:// URL or a local path. providerHint (a models.ConnectionType* git provider) overrides host-based provider detection, e.g. for a self-hosted GitLab.

func (RepoURL) CacheKey

func (u RepoURL) CacheKey() string

CacheKey is a filesystem-safe, collision-resistant directory name.

func (RepoURL) CommitURL added in v0.1.62

func (u RepoURL) CommitURL(sha string) (string, error)

func (RepoURL) DisplayName added in v0.1.72

func (u RepoURL) DisplayName() string

DisplayName identifies the repository without transport or Azure organization syntax.

func (RepoURL) FileURL added in v0.1.60

func (u RepoURL) FileURL(ref Ref, path string) (string, error)

FileURL is the provider's web page for path (repository-relative, slash-separated) on ref: a branch or tag by its name, so the page follows the branch; any other ref (a SHA, a detached HEAD) by its commit.

func (RepoURL) FullName

func (u RepoURL) FullName() string

FullName is the provider's repository path without the host.

func (RepoURL) LocalPath added in v0.1.64

func (u RepoURL) LocalPath() (string, bool)

LocalPath is the directory of a local repository (a path or file:// URL); reads open it in place instead of mirroring it.

func (RepoURL) Redacted

func (u RepoURL) Redacted() string

Redacted is the clone URL with any user info removed, for display.

func (RepoURL) RefWebURL added in v0.1.62

func (u RepoURL) RefWebURL(options WebRefOptions) (string, error)

func (RepoURL) SameRepository added in v0.1.72

func (u RepoURL) SameRepository(other RepoURL) bool

SameRepository reports whether u and other address one repository, whatever the transport: host without port and path without a .git suffix, compared case-insensitively (a local path exactly).

func (RepoURL) Short

func (u RepoURL) Short() string

Short is host/path without scheme, user or query; a local path for file URLs.

func (RepoURL) SourceRepository added in v0.1.62

func (u RepoURL) SourceRepository(name string) (RepoURL, error)

SourceRepository resolves a pull request's provider-native source name into a repository on the same host, including fork and Azure project identity.

type Repository

type Repository struct {
	URL  RepoURL
	Auth Auth
	// Provider opens pull requests; nil or a generic git provider has none.
	Provider          Provider
	ReadCache         *readcache.Cache
	SecurityNamespace string
}

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

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

NewRepository parses the URL and validates the credentials.

func (*Repository) CacheKey added in v0.1.72

func (r *Repository) CacheKey() string

func (*Repository) InvalidateRefs added in v0.1.72

func (r *Repository) InvalidateRefs(ctx context.Context) error

func (*Repository) LsRemote

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

LsRemote lists the remote's refs with go-git against in-memory storage; TLS settings are passed per call. A local repository is listed by the git binary (lsRemoteLocal).

func (*Repository) OpenPullRequest

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

OpenPullRequest opens a pull request from the existing remote branch Head into Base, pushing nothing: a whole-branch promotion. Both must be branches on the remote. A provider without pull requests returns ErrPullRequestsUnsupported before the remote is listed.

func (*Repository) Resolve

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

Resolve lists the remote and resolves ref (see RemoteRefs.Resolve); an empty ref is the remote HEAD. A full 40-character SHA is the commit itself, without listing the remote, even if a branch or tag carries that name.

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 SharedOwner added in v0.1.72

type SharedOwner struct {
	Owner     string    `json:"owner"`
	Base      string    `json:"base"`
	Commits   int       `json:"commits"`
	Committed time.Time `json:"committed"`
}

SharedOwner is a cached mirror holding part of a repository's history: Base is the merge base of the probed ref with the mirror's newest commit, Commits the number of commits in Base's history and Committed when Base was committed.

type Signature

type Signature struct {
	Name  string
	Email string
}

Signature is a commit author or tag tagger.

func DefaultIdentity

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

DefaultIdentity reads user.name and user.email from the calling process's own global git config, as the git binary resolves it from the process environment (HOME, XDG_CONFIG_HOME, GIT_CONFIG_GLOBAL). Every other command in this package runs with the global config isolated (baseEnv); this is the one read of it, so a server can author a commit as itself. A missing name or email is ErrNoIdentity.

type SourceChange added in v0.1.62

type SourceChange struct {
	Path   string
	Status FileStatus
}

SourceChange uses a slash-separated, repository-relative literal path. Renames are a deletion and addition.

type SourceInfo added in v0.1.62

type SourceInfo struct {
	Kind           SourceKind
	RepositoryRoot string
	Dir            string
	// BaseCommit is empty for an initial commit or an unborn checkout.
	BaseCommit string
	// TargetCommit is populated only for SourceCommit.
	TargetCommit string
	// TreeID is the native Git tree ID for commit and staged sources; live worktrees have none.
	TreeID string
}

SourceInfo separates the source's temporary read location from its original checkout and Git identity.

type SourceKind added in v0.1.62

type SourceKind string
const (
	SourceWorktree SourceKind = "worktree"
	SourceCommit   SourceKind = "commit"
	SourceStaged   SourceKind = "staged"
)

type SourceOptions added in v0.1.62

type SourceOptions struct {
	Directory string
	Kind      SourceKind
	// Revision is required only for SourceCommit: one commit, A..B, or A...B.
	Revision string
}

SourceOptions selects a local repository source. Directory may be any directory inside its checkout.

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 Tree added in v0.1.62

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

Tree is a read-only filesystem over one immutable Git commit.

func (*Tree) Close added in v0.1.62

func (t *Tree) Close() error

func (*Tree) Info added in v0.1.62

func (t *Tree) Info() TreeInfo

func (*Tree) Metadata added in v0.1.62

func (t *Tree) Metadata(options InspectOptions) (Metadata, error)

Metadata describes the captured commit without inspecting a worktree or traversing its ancestry. Dirty is empty because the tree is immutable.

func (*Tree) Open added in v0.1.62

func (t *Tree) Open(name string) (fs.File, error)

func (*Tree) ReadDir added in v0.1.62

func (t *Tree) ReadDir(name string) ([]fs.DirEntry, error)

func (*Tree) ReadFile added in v0.1.62

func (t *Tree) ReadFile(name string) ([]byte, error)

type TreeInfo added in v0.1.62

type TreeInfo struct {
	SHA          string
	GitDirectory string
}

TreeInfo identifies a tree's immutable commit and original object database.

type TreeOptions added in v0.1.62

type TreeOptions struct {
	Repository *Repository
	Directory  string
	Revision   string
}

TreeOptions selects an immutable commit from one cached remote repository or one existing local repository. Directory accepts working and bare repositories.

type VisibilityOptions added in v0.1.72

type VisibilityOptions struct {
	Directory         string
	Paths             []VisibilityPath
	Overrides         []string
	OverrideDirectory string
}

type VisibilityPath added in v0.1.72

type VisibilityPath struct {
	Path      string `json:"path"`
	Directory bool   `json:"directory"`
}

type VisiblePaths added in v0.1.60

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

VisiblePaths contains tracked and unignored files and their parent directories. Outside a Git checkout, every filesystem path is visible.

func ListVisiblePaths added in v0.1.60

func ListVisiblePaths(ctx context.Context, directory string) (VisiblePaths, error)

ListVisiblePaths applies .gitignore and repository exclude rules beneath directory. Contains accepts absolute paths. Tracked files remain visible even if an ignore rule matches. Global excludes are not read because git commands in this package isolate global configuration.

func (VisiblePaths) Contains added in v0.1.60

func (visible VisiblePaths) Contains(path string) bool

Contains reports whether an absolute path is tracked or unignored in this checkout.

func (VisiblePaths) IsIgnored added in v0.1.60

func (visible VisiblePaths) IsIgnored(ctx context.Context, path string) (bool, error)

IsIgnored checks a path against the checkout's ignore rules, including a nested Git directory that ls-files in the parent checkout may omit.

type WebRefOptions added in v0.1.62

type WebRefOptions struct {
	Repository string
	Ref        string
	Kind       RefKind
}

type WorkingBlame added in v0.1.72

type WorkingBlame struct {
	Lines       []BlameLine `json:"lines"`
	Unavailable string      `json:"unavailable,omitempty"`
}

func BlameWorkingFile added in v0.1.72

func BlameWorkingFile(ctx context.Context, options WorkingBlameOptions) (WorkingBlame, error)

BlameWorkingFile returns provenance independently of loading working-tree text. Unborn and untracked files have a meaningful unavailable state, not a read error.

type WorkingBlameOptions added in v0.1.72

type WorkingBlameOptions struct {
	Directory string
	Path      string
	Contents  []byte
}

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 (*Worktree) Commit

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

Commit stages every change in the worktree and commits it.

func (*Worktree) CreateBranch

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

CreateBranch creates name at the current commit and switches to it.

func (*Worktree) CreateTag

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

CreateTag tags the current commit, annotated when Message is set.

func (*Worktree) DeleteFile

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

DeleteFile removes a worktree-relative file; a missing file is an error.

func (*Worktree) Push

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

Push pushes the branch and tags to the worktree's repository.

func (*Worktree) Release

func (w *Worktree) Release() error

Release gives the worktree lease back. An ephemeral worktree is removed from disk and the mirror, with the branches and tags it created.

func (*Worktree) WriteFile

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

WriteFile writes content to the worktree-relative path, creating parents.

type WorktreeState added in v0.1.72

type WorktreeState struct {
	Name   string `json:"name"`
	Leased bool   `json:"leased"`
}

WorktreeState is a persistent or ephemeral worktree; Leased while a Checkout holds it.

Directories

Path Synopsis
Package gittest builds isolated local Git fixtures through the shared runner.
Package gittest builds isolated local Git fixtures through the shared runner.
internal

Jump to

Keyboard shortcuts

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