git

package
v1.7.0-beta.3 Latest Latest
Warning

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

 Go to latest Published: Jul 23, 2026 License: MPL-2.0 Imports: 21 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	CommitDelimiter      string = "@sha256:"
	PullRequestReference string = "(?:pull|merge-requests)/([0-9]+)/head"
	SubPathDelimiter     string = "@subpath:"
)

Variables

View Source 
var (
	ScopeDefault = ConfigScope{}
	ScopeLocal   = ConfigScope{/* contains filtered or unexported fields */}
	ScopeGlobal  = ConfigScope{/* contains filtered or unexported fields */}
	ScopeSystem  = ConfigScope{/* contains filtered or unexported fields */}
)
View Source 
var (
	HostGitHub = Host{
		Name: hostNameGitHub,
		// contains filtered or unexported fields
	}
	HostGitLab = Host{
		Name: hostNameGitLab,
		// contains filtered or unexported fields
	}
)
View Source 
var ErrGitNotFound = errors.New("git binary not found in PATH")

ErrGitNotFound is returned when the git binary is not available on PATH.

Functions

func GetBranchNameForPR 

func GetBranchNameForPR(ref string) string

GetBranchNameForPR returns the local branch name for a request ref, using the provider convention encoded in the ref (PR<n> for GitHub, MR<n> for GitLab).

func GetDefaultExtraEnv 

func GetDefaultExtraEnv(strictHostKeyChecking bool) []string

func GetIDForPR 

func GetIDForPR(ref string) string

GetIDForPR returns the lowercased request identifier used in workspace IDs.

func InstallBinary 

func InstallBinary(ctx context.Context) error

InstallBinary installs the git binary if it is not already available, using a system package manager.

func InstallLFS added in v1.4.1 

func InstallLFS(ctx context.Context) error

InstallLFS installs the git-lfs binary if it is not already available.

func PingRepository 

func PingRepository(str string, extraEnv []string) bool

Types

type CloneStrategy 

type CloneStrategy string

CloneStrategy selects how much history and object data a clone fetches. 

const (
	FullCloneStrategy     CloneStrategy = ""
	BloblessCloneStrategy CloneStrategy = "blobless"
	TreelessCloneStrategy CloneStrategy = "treeless"
	ShallowCloneStrategy  CloneStrategy = "shallow"
	BareCloneStrategy     CloneStrategy = "bare"
)

func (*CloneStrategy) Set 

func (s *CloneStrategy) Set(v string) error

func (*CloneStrategy) String 

func (s *CloneStrategy) String() string

func (*CloneStrategy) Type 

func (s *CloneStrategy) Type() string

type CommandError added in v1.4.1 

type CommandError struct {
	Args     []string
	ExitCode int
	Stderr   string
	Err      error
}

CommandError describes a failed git invocation.

func (*CommandError) Error added in v1.4.1 

func (e *CommandError) Error() string

func (*CommandError) Unwrap added in v1.4.1 

func (e *CommandError) Unwrap() error

type Config added in v1.4.1 

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

Config exposes `git config` operations scoped to a repository. Obtain one via Repo.Config.

func (*Config) Add added in v1.4.1 

func (c *Config) Add(ctx context.Context, key, value string, scope ConfigScope) error

Add sets a config key to value in the given scope.

func (*Config) Get added in v1.4.1 

func (c *Config) Get(ctx context.Context, key string, scope ConfigScope) (string, error)

Get retrieves the value of a config key in the given scope. An absent key is not an error: it returns ("", nil).

func (*Config) GetAll added in v1.4.1 

func (c *Config) GetAll(ctx context.Context, key string, scope ConfigScope) ([]string, error)

GetAll retrieves all values of a multi-valued config key in the given scope. An absent key is not an error: it returns (nil, nil).

func (*Config) Set added in v1.4.1 

func (c *Config) Set(ctx context.Context, key, value string, scope ConfigScope) error

Set sets a config key to value in the given scope, replacing any existing value.

func (*Config) Unset added in v1.4.1 

func (c *Config) Unset(ctx context.Context, key string, scope ConfigScope) error

Unset removes a config key in the given scope.

func (*Config) UnsetAll added in v1.4.1 

func (c *Config) UnsetAll(ctx context.Context, key string, scope ConfigScope) error

UnsetAll removes all values of a multi-valued config key in the given scope. An absent key is not an error.

type ConfigScope added in v1.4.1 

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

ConfigScope selects which git configuration file an operation targets.

func ScopeFile added in v1.4.1 

func ScopeFile(path string) ConfigScope

ScopeFile targets a specific config file.

type GitInfo 

type GitInfo struct {
	Repository string
	Branch     string
	Commit     string
	PR         string
	SubPath    string
}

GitInfo is the parsed form of a repository reference. Branch, Commit, PR, and SubPath are independent: a reference can carry zero or more of them. PR is exclusive with Branch and Commit.

func NormalizeRepository 

func NormalizeRepository(str string) *GitInfo

NormalizeRepository parses a repository reference into its structured parts. Accepts plain URLs, the "git:<url>" workspace-source scheme, and references suffixed with @branch, @subpath:<path>, @sha256:<commit>, or a pull/merge request ref (@pull/N/head or @merge-requests/N/head). Bare host[/path] inputs are upgraded to https://.

type Host 

type Host struct {
	Name string
	// contains filtered or unexported fields
}

Host is a git provider's convention for referencing pull/merge requests: GitHub exposes them at pull/N/head, GitLab at merge-requests/N/head.

func DetectHost 

func DetectHost(repoURL string) Host

DetectHost picks the provider from a repository URL, defaulting to GitHub.

func (Host) BranchName 

func (h Host) BranchName(number string) string

func (Host) Refspec 

func (h Host) Refspec(number string) string

type Installer added in v1.4.1 

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

Installer installs git-related tools using an ordered list of strategies.

type LFSMode added in v1.4.1 

type LFSMode int

LFSMode controls how Git LFS is handled after a clone. 

const (
	// LFSFull registers the LFS filters and downloads LFS content. This matches
	// git's default clone behavior and is the zero value.
	LFSFull LFSMode = iota
	// LFSSetupOnly registers the LFS filters but does not download content,
	// leaving pointer stubs. Future checkouts/pulls will hydrate on demand.
	LFSSetupOnly
	// LFSSkip does nothing: no filters, no download.
	LFSSkip
)

func (*LFSMode) Set added in v1.4.1 

func (m *LFSMode) Set(v string) error

func (LFSMode) String added in v1.4.1 

func (m LFSMode) String() string

func (*LFSMode) Type added in v1.4.1 

func (m *LFSMode) Type() string

type Option 

type Option func(*cloneConfig)

Option configures a clone performed by Repo.Clone or Repo.CloneFromInfo.

func WithBranch added in v1.4.1 

func WithBranch(branch string) Option

WithBranch clones only the named branch.

func WithCloneStrategy 

func WithCloneStrategy(strategy CloneStrategy) Option

WithCloneStrategy selects the clone strategy. An empty strategy is treated as FullCloneStrategy.

func WithCredentialHelper added in v1.4.1 

func WithCredentialHelper(helper string) Option

WithCredentialHelper configures a git credential helper for the clone.

func WithLFSMode added in v1.4.1 

func WithLFSMode(mode LFSMode) Option

WithLFSMode selects how Git LFS is handled after the clone. The default is LFSFull.

func WithRecursiveSubmodules 

func WithRecursiveSubmodules() Option

WithRecursiveSubmodules clones submodules recursively.

func WithSkipLFS 

func WithSkipLFS() Option

WithSkipLFS disables Git LFS smudge and hydration for the clone. Equivalent to WithLFSMode(LFSSkip).

type Repo added in v1.4.1 

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

Repo is a handle to a git repository at a filesystem path.

func At added in v1.4.1 

func At(path string, opts ...RepoOption) *Repo

At returns a Repo rooted at path.

func (*Repo) CheckoutPR added in v1.4.1 

func (r *Repo) CheckoutPR(ctx context.Context, repoURL, prRef string) error

CheckoutPR fetches a pull/merge request into a local branch and switches to it. The request number is taken from prRef; the remote refspec is resolved against repoURL's hosting provider, falling back to the other known conventions when the detected one has no such ref (e.g. self-hosted GitLab on a custom domain that URL detection can't recognize).

func (*Repo) Clone added in v1.4.1 

func (r *Repo) Clone(ctx context.Context, repository string, options ...Option) error

Clone clones repository into the repo's path using the given options.

func (*Repo) CloneFromInfo added in v1.4.1 

func (r *Repo) CloneFromInfo(
	ctx context.Context,
	gitInfo *GitInfo,
	helper string,
	options ...Option,
) error

CloneFromInfo clones the repository described by gitInfo into the repo's path, using the given credential helper and options.

func (*Repo) Config added in v1.4.1 

func (r *Repo) Config() *Config

Config returns a handle for `git config` operations on the repository.

func (*Repo) CredentialFill added in v1.4.1 

func (r *Repo) CredentialFill(ctx context.Context, request string) (string, error)

CredentialFill runs `git credential fill`, feeding request on stdin and returning git's response. Used to resolve credentials via configured helpers.

func (*Repo) Fetch added in v1.4.1 

func (r *Repo) Fetch(ctx context.Context, refspec string) error

Fetch fetches the given refspec from origin.

func (*Repo) LsRemote added in v1.4.1 

func (r *Repo) LsRemote(ctx context.Context, repository string) error

LsRemote reports whether the remote repository is reachable.

func (*Repo) LsTree added in v1.4.1 

func (r *Repo) LsTree(ctx context.Context, ref string) ([]string, error)

LsTree lists the files tracked at ref, recursively, as repo-relative paths.

func (*Repo) Path added in v1.4.1 

func (r *Repo) Path() string

Path returns the repository's filesystem path.

func (*Repo) Reset added in v1.4.1 

func (r *Repo) Reset(ctx context.Context, commit string, mode ResetMode) error

Reset moves HEAD to commit using the given mode.

func (*Repo) SetupLFS added in v1.4.1 

func (r *Repo) SetupLFS(ctx context.Context, mode LFSMode)

SetupLFS configures Git LFS in the repository.

func (*Repo) Switch added in v1.4.1 

func (r *Repo) Switch(ctx context.Context, branch string) error

Switch switches the working tree to an existing branch.

type RepoOption added in v1.4.1 

type RepoOption func(*Repo)

RepoOption configures a Repo.

func WithEnv added in v1.4.1 

func WithEnv(env []string) RepoOption

WithEnv appends extra environment entries applied to every operation.

func WithRunner added in v1.4.1 

func WithRunner(runner Runner) RepoOption

WithRunner injects a command Runner, primarily for testing.

func WithStrictHostKeyChecking added in v1.4.1 

func WithStrictHostKeyChecking(strict bool) RepoOption

WithStrictHostKeyChecking appends the default SSH/terminal environment honoring the given policy.

type ResetMode added in v1.4.1 

type ResetMode string

ResetMode selects how Reset updates the index and working tree. 

const (
	ResetSoft  ResetMode = "--soft"
	ResetMixed ResetMode = "--mixed"
	ResetHard  ResetMode = "--hard"
)

type RunOptions added in v1.4.1 

type RunOptions struct {
	Binary string
	Dir    string
	Env    []string
	Args   []string
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
}

RunOptions describes one command invocation.

type RunResult added in v1.4.1 

type RunResult struct {
	Stdout []byte
	Stderr []byte
}

RunResult holds captured output.

type Runner added in v1.4.1 

type Runner interface {
	Run(ctx context.Context, opts RunOptions) (RunResult, error)
}

Runner executes a single git subcommand.

Source Files

View all Source files

Jump to

Keyboard shortcuts

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