Module git_core 

Core Git Projection and Bridge Mirror operations.

Structs

AuthoritativeGitPushOptions

Push the authoritative checkout’s Git refs directly through Sley.

DestinationReconcilePlan

The ONE reconciliation plan EVERY push destination applies, so its published refs converge to the served frontier by construction.

ExportedCommitCounts

A partition of the commits that land in the destination, computed over the SINGLE copied ref set. total is every unique commit reachable from the copied branch/tag tips; newly is the subset minted during this export run. already is the remainder. Because newly is a subset of the same walk that produced total, newly + already == total holds by construction — the summary can never report more “newly written” than “total”, and no orphan/unreferenced state (minted but reachable from no copied ref, hence never in the walk) can inflate any count.

GitProjection

Legacy-named implementation for explicit Git Projection and Bridge Mirror operations.

GitPullOutcome

LocalGitIdentity

MirrorInitGuard

RAII guard for init_mirror. When the mirror directory did not exist at acquisition time, an early Drop (panic, error return) removes the partially-initialized .heddle/git/ so a future heddle export git ... doesn’t see a half-built bare repo. Call commit() once the mirror is known-good (e.g. after a successful first export) to disarm the guard.

NegativeRefSpec

ParsedGitRef

A parsed Git ref name: its kind, short name, and owning remote.

PlannedRefDelete

A previously-exported ref the served mirror no longer carries: it must be deleted at the destination.

PlannedRefWrite

A served ref a push destination must write: its full name, the served new tip, and whether the receive-pack command must be forced.

RefSpec

RefUpdate

SyncMapping

Mapping between Heddle StateIds and Git commit object IDs.

Enums

GitProjectionError

Errors specific to Git Projection and Bridge Mirror operations.

GitPushScope

GitRefKind

The wire-level kind used for hosted Git ref updates.

RefNamespace

The content namespaces Heddle intentionally mirrors as named Git refs.

WriteThroughOutcome

WriteThroughSkipReason

Constants

REMOTE_NAME_FOR_LOCAL_GIT_REPO

Sentinel remote name for refs owned by the local repository.

Functions

apply_ref_updates

clone_url_to_bare

Clone a remote git URL into dest as a bare repository, fetching all branches and tags. Mirrors the sley remote fetch path used by fetch_network_remote but starts from an empty init_bare rather than an existing repo.

collect_import_source_ref_updates

collect_managed_ref_updates

The mirror refs heddle MANAGES, as RefUpdates — [collect_ref_updates] filtered to the names in the managed-refs record, PLUS every refs/notes/* ref (heddle’s metadata namespace, always heddle-managed and content-rebuilt rather than target-claimed through the reconcile). The export/push frontier MUST source from this rather than the raw [collect_ref_updates] so a foreign branch/tag heddle never wrote — even one pointing at a heddle-minted commit — never enters the served frontier nor the destination’s desired set (heddle#316). The FETCH path keeps using [collect_ref_updates]/[collect_ref_updates_for_fetch] (it must see every ref); only the export/push frontier is managed-filtered.

copy_local_repo_to_bare

Copy a local Git repository into a bare repository without invoking Git transport helpers. This is the local-path clone fast path used by the OSS Git-overlay workflow when the user does not have git installed.

copy_reachable_objects

copy_reachable_objects_excluding

Incremental variant of copy_reachable_objects: copy the closure reachable from roots, skipping every object in excluded.

count_exported_commits

Count and partition the commits reachable from the branch and tag tips that collect_ref_updates writes to a destination. Derived from the SAME ref set copy_mirror_to_path copies, so the reported counts equal what actually lands in the destination — including stale mirror refs left behind by a dropped Heddle thread (export does not prune them, so the commit is still copied and must still be counted; pruning would be a separate behavior change). Notes refs are excluded: they carry metadata, not history, so they don’t count as exported commits.

delete_reference_if_present

Delete a reference if present; missing-ref is a no-op. Used by the write-through rollback path to drop a branch that was created by a failed write-through but isn’t reachable from any prior state. We scope the deletion with RefPrecondition::MustExist so an unrelated concurrent writer that just updated this ref isn’t silently clobbered — if the ref vanished underneath us between our read and the delete, that’s the rollback we wanted anyway.

git_config_identity_with_global_fallback

git_err

is_reserved_git_remote_name

Whether a remote name collides with Heddle’s local-ref sentinel.

materialize_checkout_closure_from_state

Materialize the checkout .git object closure for the commit mapped to tip_state_id (tip_oid) — reconstructing every byte-faithful commit from heddle state, then resolving lossy objects from Raw Git Object Residuals (preferred) or the Bridge Mirror backstop (#568 P1 + residual foundation).

mirror_managed_refs_recorded

Whether the mirror’s managed-refs record exists on disk. Used to distinguish a genuine FIRST export after this code lands (absent → seed from the current mirror ref set so pre-existing heddle refs aren’t all misread as foreign) from a record that exists but is empty (everything was legitimately dropped — do NOT re-seed).

open_repo

parse_git_ref

Parse a fully-qualified Git ref name into its GitRefKind, short name, and owning remote. Returns None for refs outside the branch/remote-branch/tag/notes namespaces (e.g. HEAD).

plan_destination_reconcile

Build the served-frontier reconciliation plan shared by the local-path and URL/network push destinations (heddle#316 r11/r13/r16). The destination’s published refs are a PURE PROJECTION of the served frontier, restricted to heddle-owned refs: every op — create, fast-forward, forced embargo rewind, retraction delete, or skip — is DERIVED from ONE pass over the desired-vs- actual diff, and the heddle-OWNERSHIP token (recorded_tip == old) gates force AND delete UNIFORMLY. There is no separate per-operation enforcement branch to forget: a destination tip heddle never published is neither force-rewound NOR deleted (it survives) unless the user passes --force.

planned_write_names

The sorted full names of the refs a destination reconcile plan WRITES — creations, fast-forwards, and forced embargo rewinds. This is the refs_written surface heddle push reports so a git veteran (or agent) can verify the round-trip with git ls-remote. Retraction deletes are not included. Sorted because the plan’s write order derives from hash-map iteration and the reported list must be deterministic.

principal_is_default_unknown

push_authoritative_git_refs

read_exported_refs

Heddle’s exported-refs record for target_repo (full ref name → last-published tip OID), the local-path destination record. See [read_exported_refs_at].

read_mirror_managed_refs

The full ref names heddle MANAGES in the mirror (full ref name → last-published tip OID). Ok(empty) when the record is absent — callers seed a first run from the current mirror ref set; see mirror_managed_refs_recorded.

read_or_seed_mirror_managed_refs

Read the mirror’s managed-refs record, SEEDING a genuine first run (no record on disk) from the current mirror ref set so the reconcile does not misread every pre-existing heddle ref as foreign.

resolve_git_commit_identity

set_reference

thread_is_unclaimed_bootstrap

Git projection policy: a thread is considered an “unclaimed bootstrap” when it /// points at an empty-tree state with no parents. That is the exact shape of the state produced by Repository::seed_default_thread, and it cannot occur through normal user work — any snapshot advances the tip to a state with either a non-empty tree or a non-empty parents list.

write_exported_refs

Persist the local-path destination’s exported-refs record. See [write_exported_refs_at].

write_head_symref

Write HEAD as a symbolic ref pointing at branch_ref (e.g. refs/heads/main) via sley’s ref backend.

write_mirror_managed_refs

Persist the mirror’s managed-refs record. Atomic temp+rename via [write_exported_refs_at].

Type Aliases

GitProjectionResult

Type alias for Git Projection and Bridge Mirror results.