remote

package
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: Jul 27, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ProtocolSSH    = gitremote.ProtocolSSH
	ProtocolHTTPS  = gitremote.ProtocolHTTPS
	ProtocolEntire = gitremote.ProtocolEntire
)
View Source 
const CheckpointTokenEnvVar = "ENTIRE_CHECKPOINT_TOKEN"

CheckpointTokenEnvVar is the environment variable for providing an access token used to authenticate git push/fetch operations for checkpoint branches. The token is injected as an HTTP Basic Authorization header per RFC 7617: the credentials string "x-access-token:<token>" is base64-encoded and sent as "Authorization: Basic <base64>". This matches GitHub's token auth for Git HTTPS. SSH remotes ignore the token (with a warning).

Variables

This section is empty.

Functions

func Configured 

func Configured(ctx context.Context) bool

Configured reports whether a structured checkpoint_remote is configured.

func Fetch 

func Fetch(ctx context.Context, opts FetchOptions) ([]byte, error)

Fetch runs git fetch with checkpoint token injection and optional filtered fetches (--filter=blob:none when settings enable it). GIT_TERMINAL_PROMPT=0 is always set.

Callers that pass a remote name (e.g., "origin") and want filtered fetches to resolve the name to a URL (to avoid persisting promisor settings) should call ResolveFetchTarget first and pass the resolved target as opts.Remote.

func FetchBlobs 

func FetchBlobs(ctx context.Context, remote string, hashes []string) error

FetchBlobs fetches specific objects (typically blobs) by hash from a remote. Uses `git fetch-pack` rather than `git fetch` because the high-level porcelain enforces partial-clone integrity checks that reject blob-only responses with "did not send all necessary objects". Plumbing skips those checks — it just downloads the requested objects into .git/objects/pack and exits — which is exactly what we want when grabbing individual blobs by SHA. Works against GitHub for any reachable object, including blobs.

The remote should be a URL (not a remote name) to avoid persisting promisor settings onto the named remote. Use FetchURL to obtain the URL.

func FetchURL 

func FetchURL(ctx context.Context, opts ...FetchURLOptions) (string, error)

FetchURL returns the effective checkpoint fetch URL for the current repository. If strategy_options.checkpoint_remote is configured, the returned URL is derived from the origin remote's protocol/host and the configured checkpoint repo. Otherwise, the origin remote URL is returned directly.

If ENTIRE_CHECKPOINT_TOKEN is set and a checkpoint remote is configured, HTTPS is forced so the token can be used even when origin is configured via SSH.

func GetRemoteURL 

func GetRemoteURL(ctx context.Context, remoteName string) (string, error)

GetRemoteURL returns the URL configured for the named git remote.

func GetRemoteURLInDir added in v0.6.3 

func GetRemoteURLInDir(ctx context.Context, dir, remoteName string) (string, error)

GetRemoteURLInDir returns the URL configured for the named git remote in dir.

func IsNonInteractiveSSH added in v0.9.0 

func IsNonInteractiveSSH(ctx context.Context) bool

IsNonInteractiveSSH reports whether ctx was marked with WithNonInteractiveSSH.

func IsURL 

func IsURL(target string) bool

IsURL returns true if the target looks like a URL rather than a git remote name.

func LooksLikeSSHAuthFailure added in v0.9.0 

func LooksLikeSSHAuthFailure(errText string) bool

LooksLikeSSHAuthFailure reports whether errText looks like an SSH authentication failure (passphrase/PIN unavailable under BatchMode, missing agent identity, publickey rejection, etc.). Used to print an actionable ssh-agent hint from the pre-push checkpoint path.

func LsRemoteInDir 

func LsRemoteInDir(ctx context.Context, dir, remote string, patterns ...string) ([]byte, error)

LsRemoteInDir is like LsRemote but runs in a specific directory.

func PushURL 

func PushURL(ctx context.Context, pushRemoteName string) (string, bool, error)

PushURL returns the effective checkpoint push URL for the current repository. Unlike FetchURL:

  • it derives protocol from the requested push remote, not always origin
  • it skips checkpoint remote use when the push remote owner differs from the configured checkpoint remote owner

If ENTIRE_CHECKPOINT_TOKEN is set, HTTPS is forced so the token can be used even when the push remote is configured via SSH.

The boolean return value reports whether a dedicated checkpoint_remote is configured and should be used for push. When false, the returned URL is the repository's origin URL as a fallback.

func RedactURL 

func RedactURL(rawURL string) string

RedactURL removes credentials and query parameters from a URL for safe logging.

func ResolveFetchTarget 

func ResolveFetchTarget(ctx context.Context, target string) (string, error)

ResolveFetchTarget returns the git fetch target to use. When filtered fetches are enabled, configured remotes are resolved to their URL so git does not persist promisor settings onto the remote name.

func WithNonInteractiveSSH added in v0.9.0 

func WithNonInteractiveSSH(ctx context.Context) context.Context

WithNonInteractiveSSH marks ctx so every checkpoint git command spawned under it runs SSH with BatchMode=yes, failing fast instead of hanging on an interactive prompt. Set this at best-effort, non-interactive entry points such as the git pre-push hook: a blocked passphrase prompt there would hang the user's own `git push` until the checkpoint push budget kills it, with no way to type the passphrase. Foreground commands (resume, explain) leave it unset so they can still prompt.

BatchMode tradeoffs (issue #1523):

  • Passphrase-protected keys with no ssh-agent: fail fast (desired).
  • Touch-only security keys (sk-, user-presence only): still work — touch is not a terminal passphrase read.
  • PIN-protected FIDO2 keys (verify-required): PIN entry goes through ssh's passphrase reader, so BatchMode suppresses it and the push fails. Load the key into ssh-agent beforehand, or set an explicit BatchMode=no via GIT_SSH_COMMAND / core.sshCommand (respected; we do not override it).

Types

type FetchOptions 

type FetchOptions struct {
	Remote   string   // remote name or URL (required)
	RefSpecs []string // one or more refspecs / object hashes
	NoTags   bool     // adds --no-tags
	NoFilter bool     // when true, skips --filter=blob:none even if filtered fetches are enabled
	// Shallow adds --depth=1 to fetch only the tip commit and its tree. Use
	// for tip-only probes (e.g. resolving the latest checkpoint metadata)
	// where ancestry isn't needed. Creates .git/shallow state — callers that
	// later require full history should opt into Unshallow on a follow-up
	// fetch.
	Shallow bool
	// Unshallow adds --unshallow when the repository is currently shallow,
	// triggering git to download the rest of the history for the fetched ref.
	// Set this on metadata-repair / reconcile paths that need complete
	// checkpoint ancestry. Do not set on generic branch fetches — it would
	// silently convert a deliberately-shallow user clone into a full one.
	Unshallow bool
	// Depth adds --depth=<Depth>, fetching the refspec to this absolute depth.
	// Unlike Unshallow (which is repo-global) this is ref-scoped: it fully
	// fetches the named branch — healing a prior shallow boundary on it — while
	// leaving an independently-shallow source-tree clone untouched, and it does
	// not introduce shallowness on a full repo when the value exceeds the
	// branch's length. Use a value above the branch's realistic length but below
	// math.MaxInt32 (2147483647), which git special-cases as a global unshallow.
	// Ignored when zero or when Shallow is set.
	Depth     int
	Dir       string   // working directory (empty = CWD)
	ExtraArgs []string // additional flags before remote (e.g., "--no-write-fetch-head")
}

FetchOptions configures a git fetch operation.

type FetchURLOptions added in v0.6.3 

type FetchURLOptions struct {
	WorktreeRoot string
}

FetchURLOptions configures FetchURL.

type Info 

type Info = gitremote.Info

Info is an alias for gitremote.Info.

func ParseURL 

func ParseURL(rawURL string) (*Info, error)

ParseURL parses a git remote URL (SSH SCP-style or HTTPS) into its components.

type PushOptions added in v0.6.0 

type PushOptions struct {
	Remote    string
	RefSpecs  []string
	ExtraArgs []string // additional flags before remote
	Dir       string
}

PushOptions configures a git push operation.

type PushResult 

type PushResult struct {
	Output string
}

PushResult holds raw porcelain output from git push.

func Push 

func Push(ctx context.Context, remote, refSpec string) (PushResult, error)

Push runs git push --no-verify --porcelain with token injection. GIT_TERMINAL_PROMPT=0 is always set.

func PushWithOptions added in v0.6.0 

func PushWithOptions(ctx context.Context, opts PushOptions) (PushResult, error)

PushWithOptions runs git push --no-verify --porcelain with token injection. GIT_TERMINAL_PROMPT=0 is always set.

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.