discover

Documentation

Overview

Package discover scans the filesystem for git repositories. Rules: docs/design/02-data-model.md §2 and docs/design/09-config.md §2.3.

Index

• Variables
• func ExpandPath(p, home string) string
• func Roots(home string, scanRoots, configRoots []string, scanHome bool) []string
• func Scanner(ctx context.Context, opts Options, onHit func(Hit) error) error
• type HiddenPolicy
  • func ParseHiddenPolicy(s string) (HiddenPolicy, error)
• type Hit
• type Kind
  • func (k Kind) String() string
• type Options

Variables

var DefaultIgnore = []string{
	"node_modules", "vendor", ".venv", "venv", "Pods", "DerivedData",
	".Trash", "Library", ".cache", "target", "dist", "build", ".next",
	".gradle", ".m2", ".conda", ".rustup", ".cargo", ".npm", ".bun",
	".pnpm-store", ".dart_tool", "__pycache__", "go/pkg/mod",
}

DefaultIgnore is the default discover.ignore list (09-config.md §3). Entries without "/" match any path segment; entries with "/" match the trailing segments of a dir's path relative to the scan root.

var ErrCancelled = errors.New("scan cancelled")

ErrCancelled is returned when the scan context is cancelled.

Functions

func ExpandPath

func ExpandPath(p, home string) string

ExpandPath expands a leading "~" or "~/" via home (09-config.md §2.1). "~user/..." forms are not supported. Returns p unchanged when no leading tilde is present.

func Roots

func Roots(home string, scanRoots, configRoots []string, scanHome bool) []string

Roots computes the effective scan roots and deduplicates them by canonical path (docs/design/09-config.md §2.2). home is $HOME; scanRoots are --scan-root flags (REPLACE defaults); configRoots are config discover.scan_roots (ADD to $HOME); scanHome decides whether $HOME is scanned at all.

func Scanner

func Scanner(ctx context.Context, opts Options, onHit func(Hit) error) error

Scanner walks Roots and calls onHit for each repo entry found. Hits are emitted in deterministic (sorted) order per directory.

Types

type HiddenPolicy

type HiddenPolicy int

HiddenPolicy controls descent into dot-directories (09-config.md §2.3).

const (
	// HiddenSkip: never descend into hidden dirs.
	HiddenSkip HiddenPolicy = iota
	// HiddenPeek: descend up to HiddenPeekDepth levels below a hidden dir.
	HiddenPeek
	// HiddenScan: treat hidden dirs like any other.
	HiddenScan
)

func ParseHiddenPolicy

func ParseHiddenPolicy(s string) (HiddenPolicy, error)

ParseHiddenPolicy maps config strings to HiddenPolicy.

type Hit

type Hit struct {
	Path string // directory containing the .git entry (or the bare dir)
	Kind Kind
	// GitDirLine is the resolved target of a linked worktree's "gitdir:"
	// pointer (empty otherwise).
	GitDirLine string
}

Hit is one discovered repo entry.

type Kind

type Kind int

Kind classifies a discovered repo entry.

const (
	// KindMain: a directory named .git (normal repo / main worktree).
	KindMain Kind = iota
	// KindLinked: a file named .git whose first line is "gitdir: <path>"
	// (linked worktree).
	KindLinked
	// KindBare: no .git entry, but HEAD + objects/ present with core.bare
	// (only reported when IncludeBare is set).
	KindBare
)

func (Kind) String

func (k Kind) String() string

type Options

type Options struct {
	Roots           []string
	MaxDepth        int // 0 = unlimited
	Ignore          []string
	IncludeBare     bool
	FollowSymlinks  bool
	Hidden          HiddenPolicy
	HiddenPeekDepth int // levels below a hidden dir searched when HiddenPeek
}

Options configures a scan (09-config.md §1).