clonepick

Documentation

Overview

Package clonepick implements `gitmap clone-pick <repo-url> <paths>`: a partial / sparse-checkout clone of a single git repository, fetching only the requested repo-relative paths into the current working directory (or --dest).

Why a separate package (not clonefrom / clonenow / cloner)?

• clonefrom is plan-driven from a manifest (rows of url+dest+branch).
• clonenow is round-trip from `gitmap scan` output.
• cloner is the in-memory pipeline cloner used during scan.

clone-pick sits orthogonal to all three: input is one URL + a path list, output is a sparse-checkout. Sharing code with the others would force them to grow path-filter awareness they don't need.

Persistence: every successful run writes one row to the CloneInteractiveSelection table so the same selection can be re-applied later via --replay <id|name>.

See spec/01-app/100-clone-pick.md.

Index

• Constants
• func BuildGitArgs(plan Plan, dest string) []string
• func Render(w io.Writer, plan Plan) error
• func SaveSelection(p Persister, plan Plan) (int64, error)
• type Flags
  • func DefaultFlags() Flags
• type Persister
• type Plan
  • func ParseArgs(rawURL, rawPaths string, flags Flags) (Plan, error)
• type Result
  • func Execute(plan Plan, p Persister, progress io.Writer) Result

Constants

const (
	StatusOK        = "ok"
	StatusFailed    = "failed"
	StatusCancelled = "cancelled"
)

Status enum values mirror clonenow's vocabulary so downstream pipelines that grep "ok"/"failed" keep working.

Functions

func BuildGitArgs

func BuildGitArgs(plan Plan, dest string) []string

BuildGitArgs returns the argv (excluding the "git" binary) that gitClonePartial would pass to runGit for the given plan/dest. Order matches gitClonePartial in sparse.go exactly: `clone --filter=blob:none --no-checkout [--branch B] [--depth N] URL DEST`.

func Render

func Render(w io.Writer, plan Plan) error

Render writes the dry-run preview for a single Plan. Stable output (no map iteration, no time/now, no random ordering) so the goldens don't churn between runs.

func SaveSelection

func SaveSelection(p Persister, plan Plan) (int64, error)

SaveSelection records the plan and returns the new SelectionId. Skipped (returns 0, nil) when plan.DryRun is true so dry-runs never touch the database.

Types

type Flags

type Flags struct {
	Ask     bool
	Name    string
	Mode    string
	Branch  string
	Depth   int
	Cone    bool
	Dest    string
	KeepGit bool
	DryRun  bool
	Quiet   bool
	Force   bool
}

Flags is the cmd-side flag bundle, decoupled from the flag.FlagSet so the parser is testable without spinning up a full CLI.

func DefaultFlags

func DefaultFlags() Flags

DefaultFlags returns the flag bundle with the spec'd defaults. Centralised so cmd/clonepick.go and tests stay in sync.

type Persister

type Persister interface {
	SaveClonePickSelection(plan Plan) (int64, error)
}

Persister is the surface needed to save + look up selections. Implemented by *store.DB at call time; mocked in tests.

type Plan

type Plan struct {
	// Name is an optional human label persisted with the row. Empty
	// is fine -- the row still gets a SelectionId.
	Name string
	// RepoCanonicalId is the host/owner/repo form returned by
	// gitutil.CanonicalRepoID(RepoUrl). Stored separately so
	// --replay can match HTTPS↔SSH variants of the same repo.
	RepoCanonicalId string
	// RepoUrl is the canonical URL passed to `git clone`. Either the
	// user-supplied URL verbatim (when it was full) or the expanded
	// form built from the owner/repo shorthand + Mode.
	RepoUrl string
	// Mode is "https" | "ssh" -- only meaningful when the input was
	// shorthand. Persisted so --replay reproduces the same URL form.
	Mode string
	// Branch is the optional --branch argument forwarded to git
	// clone. Empty -> git uses remote HEAD.
	Branch string
	// Depth is the shallow-clone depth. 0 = full history, 1 = the
	// classic shallow checkout used by most pickers.
	Depth int
	// Cone is true when sparse-checkout cone mode applies (folder-
	// only patterns). Auto-flipped to false by ParseArgs when any
	// path looks like a glob or carries a file extension after a /.
	Cone bool
	// KeepGit controls whether .git is preserved after checkout.
	// false = files-only mode (rm -rf .git after sparse-checkout).
	KeepGit bool
	// DestDir is the destination directory relative to cwd. "."
	// means clone into the current directory (no shell handoff).
	DestDir string
	// Paths is the deduplicated, sorted list of repo-relative paths
	// to materialise. Already validated by ParseArgs (no empty,
	// no absolute, no traversal, no oversized entries).
	Paths []string
	// UsedAsk records whether --ask was passed. Persisted so
	// --replay can decide whether to re-launch the picker (for now
	// it doesn't, but keeping the bit avoids a schema migration
	// later).
	UsedAsk bool
	// DryRun, Quiet, Force are runtime-only flags (not persisted).
	// Captured on the Plan so render + execute share one source of
	// truth and don't need to thread the cmd-side cfg struct down.
	DryRun bool
	Quiet  bool
	Force  bool
}

Plan is the validated, in-memory representation of one clone-pick invocation. Built by ParseArgs (or LoadFromDB for --replay) and consumed by Render (dry-run) and Execute.

Field order mirrors the CloneInteractiveSelection schema so the persist layer can build/destructure rows without a translation map.

func ParseArgs

func ParseArgs(rawURL, rawPaths string, flags Flags) (Plan, error)

ParseArgs builds a Plan from the user-supplied URL, the comma-separated path list, and the parsed flag values.

Returns an error (not os.Exit) so the cmd layer owns the exit policy and tests can assert on the error value directly.

type Result

type Result struct {
	// Status is one of "ok" | "failed" | "cancelled". Numeric exit
	// code mapping lives in the cmd layer (cmd/clonepick.go) so the
	// constants stay co-located with the user-facing strings.
	Status string
	// SelectionId is the DB row id assigned by the persist layer.
	// 0 when DryRun was set (no row written) or when the run failed
	// before reaching the persist step.
	SelectionId int64
	// Detail is a single-line user-facing message that's already
	// printed to stderr by Execute -- duplicated on the Result so
	// callers can include it in JSON summaries without re-deriving.
	Detail string
}

Result describes what Execute did with one Plan. Returned by Execute so the cmd layer can pick an exit code without re-implementing success/failure heuristics.

func Execute

func Execute(plan Plan, p Persister, progress io.Writer) Result

Execute runs the sparse-checkout pipeline for plan and persists the selection (when not dry-run) via p. Returns a Result whose Status drives the cmd-layer exit code.

progress is where per-step git output is streamed (typically os.Stderr; io.Discard when --quiet was passed).