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. WalkDir walks folders with the same rules, including nested repositories.
- 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 deliberately reads 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. Visibility operations also read core.excludesFile from global configuration, respecting repository overrides without importing other global settings.
Index ¶
- Variables
- func ActivityMentions(body string) []string
- func CherryPickLocal(ctx context.Context, options LocalCherryPickOptions) (string, error)
- func FreshRefs(ctx context.Context) bool
- func Head(ctx context.Context, directory string) (string, error)
- func IndexFiles(ctx context.Context, options IndexFilesOptions) ([]string, error)
- func ObjectID(entry fs.DirEntry) (string, bool)
- func PushLocal(ctx context.Context, options LocalPushOptions) error
- func ReadLocalFiles(ctx context.Context, options LocalFilesOptions) (map[string]LocalFile, error)
- func Redact(text string) string
- func ValidateBranchName(name string) error
- func ValidateRevision(rev string) error
- func ValidateTagName(name string) error
- func WalkDir(ctx context.Context, root string, fn fs.WalkDirFunc) error
- func WithFetchObserver(ctx context.Context, observer FetchObserver) context.Context
- func WithFreshRefs(ctx context.Context) context.Context
- func WithReadCache(ctx context.Context, cache *readcache.Cache) context.Context
- func WithReadObserver(ctx context.Context, observer ReadObserver) context.Context
- func WithSecurityNamespace(ctx context.Context, namespace string) context.Context
- type APIError
- type AncestorsOptions
- type Auth
- type BlameAuthor
- type BlameCommit
- type BlameLine
- type BlameOptions
- type BlobRequest
- type BlobResult
- type Cache
- func (c *Cache) Ancestors(ctx context.Context, options AncestorsOptions) ([]string, error)
- func (c *Cache) Apply(ctx context.Context, repo *Repository, request ChangeRequest) (ChangeResult, error)
- func (c *Cache) Blame(ctx context.Context, repo *Repository, options BlameOptions) ([]BlameLine, error)
- func (c *Cache) Changes(ctx context.Context, options ChangesOptions) ([]Change, 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) Evict(ctx context.Context, o EvictOptions) (_ EvictResult, err error)
- func (c *Cache) Fetch(ctx context.Context, repo *Repository, options FetchOptions) (err error)
- func (c *Cache) Files(ctx context.Context, repo *Repository, sha string) ([]string, error)
- func (c *Cache) History(ctx context.Context, repo *Repository, ref string, options HistoryOptions) ([]Commit, error)
- func (c *Cache) Inventory(ctx context.Context) ([]CacheEntry, error)
- func (c *Cache) LocalFile(ctx context.Context, options LocalFileOptions) (LocalFileInfo, error)
- func (c *Cache) Log(ctx context.Context, repo *Repository, options LogOptions) ([]Commit, error)
- func (c *Cache) Maintain(ctx context.Context, options MaintainOptions) error
- func (c *Cache) MergeBase(ctx context.Context, repo *Repository, options MergeBaseOptions) (string, error)
- func (c *Cache) OpenTree(ctx context.Context, options TreeOptions) (result *Tree, err error)
- func (c *Cache) PrepareSource(ctx context.Context, options SourceOptions) (source *PreparedSource, err error)
- func (c *Cache) ReadBlobs(ctx context.Context, repo *Repository, requests []BlobRequest) ([]BlobResult, error)
- func (c *Cache) Rebind(context.Context, *Repository, RebindOptions) (RebindResult, error)
- func (c *Cache) SharedOwners(ctx context.Context, _ *Repository) ([]SharedOwner, error)
- func (c *Cache) Show(ctx context.Context, repo *Repository, sha, path string) ([]byte, error)
- type CacheEntry
- type CachedCommit
- type Change
- type ChangeRequest
- type ChangeResult
- type ChangesOptions
- type CheckoutOptions
- type CherryPickConflictError
- type CherryPickEmptyError
- type Client
- type ClientOptions
- type CloneOptions
- type Commit
- type CommitOptions
- type CommitState
- type CommitStatus
- type Comparison
- type ConnectionScope
- type DirtyStats
- type DiscoverOptions
- type Discovery
- type EvictOptions
- type EvictResult
- type FetchObserver
- type FetchOptions
- type FetchProgress
- type FileChange
- type FileCommit
- type FileStatus
- type Fingerprint
- type HistoryDetail
- type HistoryOptions
- type IndexFilesOptions
- type InspectOptions
- type LastCommit
- type ListPullRequestsOptions
- type ListRepositoriesOptions
- type LocalCherryPickOptions
- type LocalFile
- type LocalFileInfo
- type LocalFileOptions
- type LocalFilesOptions
- type LocalPushOptions
- type LocalRevision
- type LocalRevisionOptions
- type LogOptions
- type MaintainOptions
- type MergeBaseOptions
- type Metadata
- type MirrorState
- type MirrorStore
- type PackStore
- func (s *PackStore) Compact(ctx context.Context, key string) (compacted bool, err error)
- func (s *PackStore) Hydrate(ctx context.Context, key, mirror string) error
- func (s *PackStore) Inventory(ctx context.Context) ([]StoreEntry, error)
- func (s *PackStore) Publish(ctx context.Context, key, mirror string) error
- type Page
- type PathVisibility
- type PickStrategy
- type Pipeline
- type PipelineExecution
- type PipelineOptions
- type PipelineProvider
- type PreparedSource
- type Provider
- type PullRequest
- type PullRequestActivity
- type PullRequestActivityKind
- type PullRequestCheck
- type PullRequestChecksReader
- type PullRequestMetadata
- type PullRequestMetadataOptions
- type PullRequestPolicy
- type PullRequestReader
- type PullRequestRequest
- type PullRequestReview
- type PullRequestReviewReader
- type PullRequestReviewer
- type PullRequestState
- type PushOptions
- type ReadObserver
- type ReadProgress
- type RebindOptions
- type RebindResult
- type Ref
- type RefKind
- type RemoteHistoryProvider
- type RemoteMergeBaseOptions
- type RemoteRefs
- type Rename
- type RepoURL
- func (u RepoURL) CacheKey() string
- func (u RepoURL) CommitURL(sha string) (string, error)
- func (u RepoURL) DisplayName() string
- func (u RepoURL) FileURL(ref Ref, path string) (string, error)
- func (u RepoURL) FullName() string
- func (u RepoURL) LocalPath() (string, bool)
- func (u RepoURL) Redacted() string
- func (u RepoURL) RefWebURL(options WebRefOptions) (string, error)
- func (u RepoURL) SameRepository(other RepoURL) bool
- func (u RepoURL) Short() string
- func (u RepoURL) SourceRepository(name string) (RepoURL, error)
- type Repository
- func (r *Repository) BranchProtected(ctx context.Context, branch string) (bool, error)
- func (r *Repository) CacheKey() string
- func (r *Repository) InvalidateRefs(ctx context.Context) error
- func (r *Repository) LsRemote(ctx context.Context) (refs RemoteRefs, err 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 RepositoryOptions
- type SharedOwner
- type Signature
- type SourceChange
- type SourceInfo
- type SourceKind
- type SourceOptions
- type Store
- type StoreEntry
- type TLS
- type TagOptions
- type Tree
- type TreeInfo
- type TreeOptions
- type VisibilityOptions
- type VisibilityPath
- type VisiblePaths
- type WebRefOptions
- type WorkingBlame
- type WorkingBlameOptions
- type Worktree
- 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
- type WorktreeState
Constants ¶
This section is empty.
Variables ¶
var ( ErrCacheBusy = errors.New("git cache entry is in use") ErrCacheEntry = errors.New("invalid git cache entry for this action") )
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") ErrBranchProtected = errors.New("branch is protected 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") // e.g. branches of repositories that are not forks of one another. ErrUnrelatedHistories = errors.New("the commits share no history") )
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") )
var ErrNoCommitView = errors.New("no web commit view")
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.
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.
var ErrNotRepository = errors.New("not a git repository")
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).
var ErrPipelinesUnsupported = errors.New("pipelines are not supported by this git provider")
Functions ¶
func ActivityMentions ¶ added in v0.1.62
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 IndexFiles ¶ added in v0.1.72
func IndexFiles(ctx context.Context, options IndexFilesOptions) ([]string, error)
func ObjectID ¶ added in v0.1.64
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
ReadLocalFiles lists the requested entries Commit has in one spawn and reads each blob among them in one more.
func ValidateBranchName ¶
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 ¶
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 ¶
ValidateTagName applies the same ref-format rules to a tag name.
func WalkDir ¶ added in v0.1.75
WalkDir visits tracked and unignored paths, applying each nested repository's rules. Outside a repository it visits all paths. Git metadata is never visited.
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 WithReadCache ¶ added in v0.1.72
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
Types ¶
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 ¶
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.
type BlameAuthor ¶ added in v0.1.62
type BlameCommit ¶ added in v0.1.62
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
BlameOptions supplies the displayed contents of a file at an immutable commit.
type BlobRequest ¶ added in v0.1.62
BlobRequest identifies a literal file path at a full commit SHA.
type BlobResult ¶ added in v0.1.62
BlobResult distinguishes absent paths from present files with empty content.
type Cache ¶
Cache leases worktrees from per-repository bare mirrors. GitHub and Azure DevOps mirrors borrow complete objects from an organization pool.
<Root>/v2/<RepoURL.CacheKey>/mirror.git <Root>/v2/<RepoURL.CacheKey>/mirror.lock <Root>/v2/<RepoURL.CacheKey>/pins/<sha> <Root>/v2/<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.
Every cached commit is complete: a read or checkout of a missing commit fetches it with its whole history, into the organization pool for a pooled mirror (stored once, see fetchIntoPool) and into the mirror otherwise. No read creates a shallow mirror, and a shallow one is refused.
Store, when set, is the durable tier behind Root: a commit missing from a mirror is hydrated from it before the remote is asked (see Store).
func (*Cache) Ancestors ¶ added in v0.1.64
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
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, o EvictOptions) (_ EvictResult, err error)
Evict removes one repository's mirror and idle worktrees. Pool maintenance reclaims the removed mirror's retention refs after reconciling other borrowers.
func (*Cache) Fetch ¶ added in v0.1.76
func (c *Cache) Fetch(ctx context.Context, repo *Repository, options FetchOptions) (err error)
Fetch brings refs with their complete history into repo's mirror ahead of any read. It uses cached SHAs from the mirror and its pool, then hydrates missing commits from the Store. One remote fetch advances named refs and fills remaining misses. The resulting commits are retained in the pool, dropped from the mirror, and pinned so they survive gc and reach the Store.
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. A PackStore then compacts the bundles of every key it holds (of Owners only, when set). A full sweep (no Owners) first imports and removes the pre-v2 entries under Root (migrateLegacy); an import failure leaves that entry in place and fails Maintain after the rest of the sweep ran.
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
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(context.Context, *Repository, RebindOptions) (RebindResult, error)
func (*Cache) SharedOwners ¶ added in v0.1.72
func (c *Cache) SharedOwners(ctx context.Context, _ *Repository) ([]SharedOwner, error)
type CacheEntry ¶ added in v0.1.72
type CacheEntry struct {
Key string `json:"key"`
Repository string `json:"repository,omitempty"`
Owner string `json:"owner"`
Pool string `json:"pool,omitempty"`
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
UpdateExisting bool // Commit Files on the reviewed tip of Base and update that same branch.
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. UpdateExisting requires Base to be the full ref of Branch and BaseSHA to be set. The push accepts the new child commit only at that reviewed tip.
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 ¶
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 ¶
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 ¶
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) 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.
type CommitOptions ¶
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 ¶
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 ¶
func (DirtyStats) Clean ¶
func (s DirtyStats) Clean() bool
type DiscoverOptions ¶ added in v0.1.72
type DiscoverOptions struct{ Path string }
type EvictOptions ¶ added in v0.1.72
type EvictOptions struct{ Owner string }
EvictOptions selects a repository mirror by cache key.
type EvictResult ¶ added in v0.1.72
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 FetchOptions ¶ added in v0.1.76
FetchOptions configures Cache.Fetch. Refs are branches, tags and full commit SHAs (e.g. pull request heads), fetched in one git fetch. Publish then writes the mirror's new objects and refs to Cache.Store.
type FetchProgress ¶ added in v0.1.64
type FetchProgress struct {
ID string
Repository string
Ref string
// Mirror and MirrorRepository are retained for older progress consumers.
Mirror string
MirrorRepository string
// Pool identifies the organization object pool used by this fetch.
Pool 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 ¶
FileChange writes Content to Path, or deletes Path when Delete is set.
type FileCommit ¶ added in v0.1.72
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
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 InspectOptions ¶
InspectOptions carries the requested URL and ref, which a detached cache worktree cannot report itself.
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
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
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 LocalFilesOptions ¶ added in v0.1.64
LocalFilesOptions names root-relative Files (matched literally) to read at Commit of the local repository at Root.
type LocalPushOptions ¶ added in v0.1.74
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
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
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
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
}
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 MirrorStore ¶ added in v0.1.76
type MirrorStore struct {
Path string
}
MirrorStore keeps one bare mirror per repository on the shared path, in the local cache's layout:
<Path>/<key>/mirror.git the store mirror <Path>/<key>/mirror.lock shared by hydrates, exclusive for a publish <Path>/<key>/published touched by every publish
It suits a ReadWriteOnce volume or development; on NFS (EFS) every publish takes a file lock and rewrites refs there, which PackStore avoids.
func (*MirrorStore) Hydrate ¶ added in v0.1.76
func (s *MirrorStore) Hydrate(ctx context.Context, key, mirror string) (err error)
Hydrate fetches every ref of the store mirror into the local mirror under refs/commons-store/.
func (*MirrorStore) Inventory ¶ added in v0.1.76
func (s *MirrorStore) Inventory(ctx context.Context) ([]StoreEntry, error)
Inventory describes every store mirror.
type PackStore ¶ added in v0.1.76
PackStore keeps an append-only set of git bundles per repository, written without any file lock, so it suits NFS (EFS):
<Path>/<key>/packs/<unix nanos>-<random>.bundle one per publish <Path>/<key>/refs.json the published refs
Every file is written to a dot-prefixed temporary name in the same directory and renamed into place, so a reader never sees a partial file and concurrent publishers never overwrite each other's bundles. refs.json is the publishers' index of what the store already holds (each bundle carries its own refs): a lost concurrent update only makes the next bundle larger. Compact folds a key's bundles into one once it holds more than CompactAbove; Cache.Maintain calls it.
func (*PackStore) Compact ¶ added in v0.1.76
Compact folds the key's bundles into one full bundle once there are more than CompactAbove, reporting whether it did.
func (*PackStore) Hydrate ¶ added in v0.1.76
Hydrate fetches every bundle not yet applied to the local mirror.
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 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 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
// UpdatedAt is when the provider last changed the pull request (GitHub
// updated_at, GitLab updated_at). Azure DevOps reports no such time, so
// it is zero there.
UpdatedAt 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 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 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 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 }
type RebindResult ¶ added in v0.1.72
type Ref ¶
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 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
RemoteMergeBaseOptions selects two immutable commits in the target provider.
type RemoteRefs ¶
RemoteRefs are the branches and tags a remote advertises, plus its HEAD.
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 ¶
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) DisplayName ¶ added in v0.1.72
DisplayName identifies the repository without transport or Azure organization syntax.
func (RepoURL) FileURL ¶ added in v0.1.60
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) LocalPath ¶ added in v0.1.64
LocalPath is the directory of a local repository (a path or file:// URL); reads open it in place instead of mirroring it.
func (RepoURL) RefWebURL ¶ added in v0.1.62
func (u RepoURL) RefWebURL(options WebRefOptions) (string, error)
func (RepoURL) SameRepository ¶ added in v0.1.72
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).
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) BranchProtected ¶ added in v0.1.76
BranchProtected reports protection for an existing branch. With plain Git, only the remote can enforce its branch rules.
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.
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 {
}
SharedOwner describes the former owner-selection response for clients that still query the cache-owners endpoint during the transition.
type Signature ¶
Signature is a commit author or tag tagger.
func DefaultIdentity ¶
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), so a server can author a commit as itself. Other commands isolate global configuration, except for the visibility helpers' core.excludesFile lookup. 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 Store ¶ added in v0.1.76
type Store interface {
// Hydrate fetches what the store holds for key into the bare mirror; a
// key the store has nothing for is no error.
Hydrate(ctx context.Context, key, mirror string) error
// Publish writes the mirror's objects and refs the store lacks for key.
Publish(ctx context.Context, key, mirror string) error
// Inventory describes every key the store holds, sorted by key.
Inventory(ctx context.Context) ([]StoreEntry, error)
}
Store is a durable second tier under Cache: the local Root is ephemeral (an emptyDir), the store survives it on a shared volume (an EFS RWX PVC). A Cache with a Store hydrates a mirror from the store on a commit miss and fetches from the remote only what the store lacks; Cache.Fetch with Publish writes a mirror's new objects and refs back.
Keys are the same RepoURL.CacheKey layout as Root (the directory of a repository mirror). Cache mirrors hold complete histories only; a shallow mirror is never published: a shallow history would truncate every other reader's log and merge base.
type StoreEntry ¶ added in v0.1.76
type StoreEntry struct {
Key string `json:"key"`
SizeBytes int64 `json:"sizeBytes"`
Bundles int `json:"bundles,omitempty"`
Published *time.Time `json:"published,omitempty"`
}
StoreEntry is one repository in a Store. Bundles counts the pack store's bundles (zero for a mirror store); Published is the last publish.
type TLS ¶
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 ¶
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.
type TreeInfo ¶ added in v0.1.62
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 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. User-global core.excludesFile is honored without importing other global settings.
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.
type WebRefOptions ¶ added in v0.1.62
type WorkingBlame ¶ added in v0.1.72
type WorkingBlame struct {
Lines []BlameLine `json:"lines"`
}
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 Worktree ¶
Worktree is a leased checkout from a Cache. Release it when done.
func (*Worktree) CreateBranch ¶
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 ¶
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.
type WorktreeState ¶ added in v0.1.72
WorktreeState is a persistent or ephemeral worktree; Leased while a Checkout holds it.
Source Files
¶
- activity_mentions.go
- ancestry.go
- auth.go
- blame.go
- blame_parse.go
- blobs.go
- branch_protection.go
- cache.go
- cache_admin.go
- cache_inventory.go
- cache_refs.go
- cached_history.go
- change.go
- change_index.go
- changes.go
- cherrypick.go
- cli.go
- cli_auth.go
- clone.go
- clone_cache.go
- clone_tag.go
- connection_scope.go
- discover.go
- doc.go
- excludes.go
- factory.go
- fetch.go
- fetch_progress.go
- fingerprint.go
- identity.go
- ignore.go
- index_files.go
- inspect.go
- legacy.go
- local_change.go
- local_file_info.go
- local_repository.go
- log.go
- maintain.go
- mixed_refs.go
- object_batch.go
- object_pool.go
- object_stream.go
- pins.go
- pipelines.go
- pipelines_azure.go
- pipelines_github.go
- pool_maintain.go
- provider.go
- provider_azure.go
- provider_azure_review.go
- provider_checks.go
- provider_git.go
- provider_github.go
- provider_gitlab.go
- provider_review.go
- pullrequest_metadata.go
- push.go
- read.go
- read_cache.go
- read_progress.go
- refname.go
- refs.go
- remote.go
- remote_history.go
- rest.go
- show.go
- source.go
- source_changes.go
- source_materialize.go
- source_repository.go
- store.go
- store_mirror.go
- store_pack.go
- strategy.go
- tree.go
- tree_fs.go
- tree_node.go
- url.go
- url_azure.go
- url_file.go
- visibility.go
- walk.go
- working_blame.go
- worktree.go
- worktree_refs.go