Documentation
¶
Overview ¶
Package discover finds the repositories to operate on by reconciling the local ~/projects/{org}/{repo} tree with the non-archived repositories GitHub reports for the relevant orgs.
Index ¶
Constants ¶
const LocalIndexSchemaVersion = 1
Variables ¶
This section is empty.
Functions ¶
func IsArchived ¶ added in v0.60.0
IsArchived confirms, live against GitHub, whether the repository named by slug ("owner/repository") is archived right now. It is deliberately a single per-repository query rather than a reuse of a fleet-wide listing (ListRemote, or a caller's own cached Repo.Archived): a bulk listing can be stale by the time a destructive decision is made from it, can silently omit a repository the caller lacks org-listing access to, and answers "was this archived when the list was built" rather than "is this archived now". A caller about to delete a local clone based on archived status must ask this exact question about this exact repository immediately before acting, and must treat any error (network, auth, rate limit, unknown repository) as "could not confirm" rather than guessing either way.
func MemberOrgs ¶
MemberOrgs returns the GitHub orgs the authenticated user belongs to. This is the authoritative source of "owners I control" — local directory names are not, since they include third-party clones.
Types ¶
type CanonicalRepository ¶ added in v0.115.0
CanonicalRepository is GitHub's current identity for a possibly redirected owner/name URL.
func ResolveCanonicalRepository ¶ added in v0.115.0
func ResolveCanonicalRepository(ctx context.Context, repo Repo) (CanonicalRepository, error)
ResolveCanonicalRepository follows GitHub's repository redirect and returns the current owner/name and transport URL for one local clone.
type LocalIndexOptions ¶ added in v0.111.3
LocalIndexOptions configures the persisted read-only fleet index. A blank CachePath deliberately falls back to a fresh scan. Callers that can mutate a repository continue to use ScanLocal so cached discovery never grants write authority.
type LocalIndexResult ¶ added in v0.111.3
type LocalIndexResult struct {
Repositories []Repo
SourceFingerprint string
ObservedAt time.Time
CacheHit bool
Diagnostics []string
}
LocalIndexResult describes whether discovery reused a persisted observation. Diagnostics are cache-only failures: fresh discovery still succeeds when a cache is corrupt or temporarily unwritable.
func ScanLocalIndexed ¶ added in v0.111.3
func ScanLocalIndexed(projectsRoot string, options LocalIndexOptions) (LocalIndexResult, error)
ScanLocalIndexed reuses a persisted canonical-clone inventory only for a bounded time and only while the projects root and organization-directory metadata fingerprint is unchanged. Nested changes that do not update an organization directory are bounded by MaxAge. The index is discovery data, never mutation evidence.
type Repo ¶
type Repo struct {
Org string
Name string
Host string // literal forge hostname of the placement, empty for a legacy flat clone
Path string // local working-tree path; empty if not cloned locally
CloneURL string // transport URL from GitHub; empty if only known locally
Archived bool
IsFork bool
Local bool
Remote bool
// TransferFrom is set when this remotely listed repository is the
// canonical identity GitHub returns for a local clone still stored under
// an older owner/name path.
TransferFrom string
DefaultBranch string
TransferError string
}
Repo identifies a single repository and where it lives.
func ListRemote ¶
ListRemote returns all repos for owner via gh. The archived flag is preserved so callers can report and skip archived repos explicitly.
func Reconcile ¶
Reconcile merges locally-cloned repos with remotely-listed ones.
Entries are keyed by their host-qualified Identity, so two clones of the same owner/repository on different forges stay two entries instead of silently collapsing into one — the multi-forge case the host level exists to express. Remote metadata (archived flag, clone URL) wins where a remote listing describes a repository that is already cloned locally. The result is sorted by slug, then host and path, for deterministic output.
func ReconcileTransfers ¶ added in v0.115.0
func ReconcileTransfers(ctx context.Context, repos []Repo, resolve func(context.Context, Repo) (CanonicalRepository, error)) []Repo
ReconcileTransfers folds an old-path local-only repository and its new remote-only identity into one repository. This must happen before sync's worker pool so no worker clones the destination while another moves source.
func ScanLocal ¶
ScanLocal walks projectsRoot and returns every canonical git repository.
Canonical clones live at <root>/{host}/{org}/{repo} with the literal forge hostname at the first level; the legacy two-level <root>/{org}/{repo} placement is read as well, so a fleet that has not adopted the host level stays fully visible and a migrated one is never read as empty. Linked worktrees use a .git file and are excluded: they are alternate checkouts of a canonical repository, not fleet members.
func (Repo) Identity ¶ added in v0.138.0
Identity is the repository's host-qualified address when its placement knows the forge, and the bare owner/repository slug otherwise. Two clones of the same owner/repository on different forges are different repositories: they must never collapse into one inventory entry, which is much of why the host level exists.
Source Files