git

Documentation

Overview

Package git provides repository checkouts for scanners that operate on source trees.

Index

• func Checkout(ctx context.Context, url, revision string, scope Scope) (dir string, cleanup func(), err error)
• func IsLocalPath(url string) bool
• func UncommittedFiles(ctx context.Context, url string) int
• type Scope
  • func (s Scope) Empty() bool
  • func (s Scope) Key() string

Functions

func Checkout

func Checkout(ctx context.Context, url, revision string, scope Scope) (dir string, cleanup func(), err error)

Checkout clones url into a fresh temporary directory, materialising only what scope allows. With an empty revision it does a shallow clone of the default branch; otherwise it clones and checks out revision. The returned cleanup removes the directory (call it even on error paths that returned a dir).

func IsLocalPath

func IsLocalPath(url string) bool

IsLocalPath reports whether url names a directory on this machine rather than a remote.

Deliberately a filesystem question rather than a URL-parsing one: "." and "../service" and an absolute path are all local, and anything with a scheme or an scp-style host is not.

func UncommittedFiles

func UncommittedFiles(ctx context.Context, url string) int

UncommittedFiles counts a local repository's uncommitted changes, or 0 when there are none, the path is not local, or git cannot say.

Exists because a local path is cloned like any other source: the scan sees the *committed* state, not the files on disk. That is right — a scan has to describe a revision someone else can reproduce — and it is invisible, so a change that introduces a finding passes until it is committed. Best-effort: a scan must not fail because git could not answer a courtesy question.

Types

type Scope

type Scope struct {
	// Paths restricts the checkout to these directories. Empty means the whole repository.
	//
	// Directory prefixes, not general globs: `services/web` and `services/web/**` both mean the
	// same subtree. That is what sparse checkout can express, and expressing it any other way
	// would mean downloading the repository to throw most of it away.
	Paths []string

	// Ignore removes matching paths after checkout, applied last so it can carve out of Paths.
	// Gitignore-style: a trailing `/` matches a directory and everything under it, `*` matches
	// within a path segment, `**` matches across them.
	Ignore []string
}

Scope restricts which of a repository's files a checkout materialises.

Shaping the tree rather than passing flags to each tool is deliberate. Every repository scanner is handed the checkout directory and points its tool at it — Trivy, Semgrep, Gitleaks and gosec all take a root and walk it. Translating a descriptor's scope into each tool's own include and exclude syntax would be a mapping per tool, wrong in a different way for each, and absent for the next scanner someone adds. A tree that already contains what was asked for needs no translation and cannot be forgotten.

func (Scope) Empty

func (s Scope) Empty() bool

Empty reports whether the scope restricts anything.

func (Scope) Key

func (s Scope) Key() string

Key renders the scope for a cache or dedup identity. Two components scoped to different subtrees of one repository are different scans, and a key that cannot tell them apart lets the second silently receive the first's findings.