remote

package
v0.10.0 Latest Latest
Warning

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

 Go to latest Published: Aug 12, 2026 License: MIT Imports: 22 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).

View Source 
const WriteProbeFetchBudget = 15 * time.Second

WriteProbeFetchBudget bounds the on-demand ref fetch performed by a BACKFILL's absence probe. Write paths run inside git hooks (post-commit, stop-time finalize) where a dead network must not stall the user's workflow for the read path's full fetch window; combined with the per-store failure memo in the git-refs store, a loop over N checkpoints pays a dead network once, briefly.

Variables

This section is empty.

Functions

func BoundedCheckpointRefFetcher added in v0.10.0 

func BoundedCheckpointRefFetcher(d time.Duration) func(context.Context, plumbing.ReferenceName) error

BoundedCheckpointRefFetcher returns a RefFetchFunc-shaped fetcher whose per-call budget is capped at d, for wiring into write-path checkpoint stores (see WriteProbeFetchBudget).

func CheckpointFetchTarget added in v0.10.0 

func CheckpointFetchTarget(ctx context.Context) string

CheckpointFetchTarget returns the git remote (URL or name) that checkpoint data is fetched from. It prefers the effective URL resolved by FetchURL, which is the source of truth for checkpoint fetch location. If URL resolution fails, it falls back to the origin remote name so callers can still attempt a fetch.

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 FetchCheckpointRef added in v0.10.0 

func FetchCheckpointRef(ctx context.Context, ref plumbing.ReferenceName) error

FetchCheckpointRef fetches a single per-checkpoint ref (refs/entire/checkpoints/<shard>/<id>) from the checkpoint remote into the local ref of the same name, so the git-refs store can resolve a checkpoint written on another machine.

Contract — absence is distinguishable from failure:

  • The remote genuinely lacking the ref returns an error wrapping plumbing.ErrReferenceNotFound (probed via ls-remote before fetching, because `git fetch` of a missing refspec fails indistinguishably from a transport error). Store probes classify this as "checkpoint not found", which write routing may legitimately act on.
  • Any transport-level failure (probe or fetch) is surfaced as a real error, never mapped to absence — a false "absent" would misdirect a backfill onto another backend instead of retrying.
  • A repository with no git remotes at all and no checkpoint_remote configured also returns an error wrapping plumbing.ErrReferenceNotFound without probing: there is no remote that could host the ref.

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 GetPushURL added in v0.10.0 

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

GetPushURL returns the URL a push to remoteName delivers to. A remote's push destination is remote.<name>.pushurl when set and only otherwise its url, so reading the plain url (as GetRemoteURL does) can name a different repository than the one being pushed to.

When several push URLs are configured this returns the FIRST, which is not an arbitrary pick: resolveRefsPushDestination sends checkpoint refs to exactly that URL, so the URL this derives transport and (origin-less) ownership from is the URL the checkpoints land in.

func GetPushURLs added in v0.10.0 

func GetPushURLs(ctx context.Context, remoteName string) ([]string, error)

GetPushURLs returns every URL a push to remoteName delivers to, in the order git will use them. See gitremote.GetPushURLs for why this differs from GetRemoteURL.

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 HookCheckpointRefFetcher added in v0.10.0 

func HookCheckpointRefFetcher() func(context.Context, plumbing.ReferenceName) error

HookCheckpointRefFetcher returns the write-probe fetcher for git-hook contexts (post-commit attribution, stop-time transcript finalize): the bounded budget plus BatchMode SSH, so a passphrase-protected key can never prompt — or invisibly hang — inside a hook the user's git command is waiting on.

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 RedactURLOrPath added in v0.10.0 

func RedactURLOrPath(target string) string

RedactURLOrPath is RedactURL for values that may be a remote name or a local path rather than a URL. See gitremote.RedactURLOrPath.

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.