Crate sley_remote

Expand description

git-remote — callable fetch / push / clone / ls-remote orchestration.

This crate lifts the network-transport orchestration out of the git-cli monolith so it can be driven as a library (the way a downstream consumer such as heddle needs). The wire codecs (sley_protocol), the pack encoder (sley_pack), pack building (sley_odb) and ref/commit plumbing already live in their own crates; git-remote is the glue that sequences them into fetch/push/clone/ls-remote, with the CLI-specific concerns (argument parsing, stdout/stderr formatting, exit codes, repository discovery from process-global state) kept out via the seams below:

CredentialProvider — how authenticated remotes obtain credentials. The caller injects one (e.g. a credential-helper-backed impl, an interactive prompt, or NoCredentials for unauthenticated/public access).
ProgressSink — where human-facing progress/summary lines go. The orchestration returns structured outcomes and emits progress through this sink instead of printing, so the caller controls presentation.

The lift proceeds in stages (see docs/git-remote-extraction.md); this is the scaffold (stage A).

Structs§

CloneOptions: The clone inputs the library needs for the branch-tracking flow, all resolved by the caller. The remaining git clone knobs (bare/mirror, --revision, templates, config overrides, sparse, separate-git-dir, etc.) stay in the CLI: the unsupported ones are gated before clone is called, and the config-writing ones run inside the configure/configure_branch callbacks.
CloneOutcome: The structured result of a clone.
CloneRequest: Fully resolved inputs for a clone run.
CloneServices: Mutable seams used while cloning.
CredentialHelperProvider: The default CredentialProvider: fills and stores credentials via the repository’s configured credential.helper programs.
FetchBundleRequest: Fully resolved inputs for a fetch_bundle run.
FetchOptions: Controls for a fetch run, mirroring the git fetch flags the CLI parses.
FetchOutcome: The structured result of a fetch.
FetchRequest: Fully resolved inputs for a fetch run.
FetchServices: Mutable seams used while fetching.
GitFetchPackRequest
HttpFetchPackRequest: Fetch wants from an HTTP upload-pack remote into the repository at git_dir, installing the resulting pack. Objects already present locally are skipped (for non-shallow fetches); promisor selects promisor-pack installation.
HttpServiceAdvertisements: Result of smart-HTTP service discovery: parsed ref advertisements plus the protocol v2 handshake when the server negotiated v2 on the info/refs exchange.
LocalDeepenPlan: The in-process upload-pack’s plan for a deepen (shallow) local fetch: which shallow/unshallow updates to report, which commits the pack walk must stop at, and which extra tips become packable because the client’s boundary moved.
LsRemoteFilter: The ref-class filters that select which advertised refs to keep, mirroring the git ls-remote flags the CLI parses.
LsRemoteRecord: One advertised ref returned by ls_remote — what the CLI prints as a <oid>\t<name> line (with an optional preceding ref: <symref>\t<name> line when --symref is set and symref is present).
NoCredentials: A CredentialProvider that never supplies credentials, so every request is attempted unauthenticated. This is what an embedder targeting public remotes (e.g. heddle) uses to suppress prompts.
PrunedRef: A remote-tracking ref removed by a prune pass.
PushActionPlan: A caller-authored push plan. This is distinct from PushPlan, which is a negotiated, executable transport token returned by plan_push.
PushActionRequest: Fully resolved inputs for a caller-authored exact push plan.
PushCommand: One caller-authored receive-pack command.
PushOptions: Controls for a push run, mirroring the git push flags the CLI parses that affect the wire/planning behavior the library owns.
PushOutcome: The structured result of a push.
PushPackRequest: Inputs for building a push packfile or full receive-pack request body.
PushPlan: A push after ref negotiation and command planning, but before any ref update is sent or applied.
PushReportRef: One ref’s line in git’s push status report. Carries everything print_one_push_report needs: the source (“from”) ref, the destination (“to”) ref, the old/new object ids, whether the update was forced, whether it is a deletion, and the classified PushRefStatus.
PushReportRequest: Fully resolved inputs for a status-reporting push to a local repository.
PushRequest: Fully resolved inputs for a push run.
PushServices: Mutable seams used while pushing.
PushStatusReport: The full result of a push as git’s transport layer models it: every ref’s classified status, ready to be rendered into the “To ” report and used to decide the process exit code and the pull-before-push advice.
SilentProgress: A ProgressSink that discards every event.
SshFetchPackRequest: Fetch wants from an SSH upload-pack remote into the repository at git_dir, installing the resulting pack. Objects already present locally are skipped (for non-shallow fetches); promisor selects promisor-pack installation.
TransportCapabilities: Transport and remote-operation capabilities exposed by sley-remote.

Enums§

CloneSource: How clone reaches the remote it is cloning from.
FetchSource: How a fetch obtains refs and objects from the remote.
LsRemoteSource: How ls_remote obtains the ref advertisements.
PushAction: A typed push action that preserves the caller’s exact old/new/delete intent.
PushDestination: How a push delivers refs and objects to the remote.
PushRefStatus: Per-ref outcome of a push, mirroring git’s enum ref_status so the CLI can reproduce transport_print_push_status byte-for-byte. Ok covers create, update, forced update, and delete (disambiguated by the old/new ids on the owning PushReportRef); the remaining variants are the rejection reasons.
RemoteTransportKind: Coarse transport classification for capability lookups.

Constants§

BUNDLE_FETCH_SUPPORTED: Flip to true once bundle fetch is lifted from the CLI.
HTTP_PROTOCOL_V2_FETCH: Flip to true once HTTP v2 fetch RPC is wired (see http.rs).
INFINITE_DEPTH: Upstream INFINITE_DEPTH: --unshallow, and the implicit deepen a shallow server runs for a plain fetch so its graft points reach the client.
SSH_CLONE_SUPPORTED: Flip to true once CloneSource::Ssh lands.
THIN_PACK_PUSH_SUPPORTED: Thin-pack push via crate::pack::build_push_packfile (PushPackRequest::thin).

Traits§

CredentialProvider: Supplies credentials for an authenticated remote, mirroring git’s credential protocol: fill is handed a partial GitCredential describing the request (protocol/host/path) and returns a completed credential, or None to proceed unauthenticated.
ProgressSink: Receives human-facing progress and summary events from an operation (the “To ” push summary, prune notices, “Cloning into…”, etc.). The orchestration returns structured outcomes regardless; this is purely for presentation, so the default implementations discard everything.

Functions§

append_reachable_auto_follow_tags: Append tags reachable from the fetched (non-tag) commits, using the remote object database to test reachability.
apply_configured_fetch_prune_option: Apply the configured remote.<name>.prune (then fetch.prune) unless the prune option was set explicitly on the command line.
apply_configured_remote_tag_option: Apply the configured remote.<name>.tagopt unless the tag option was set explicitly on the command line.
apply_shallow_info: Fold the server’s shallow-info entries into $GIT_DIR/shallow: the new boundary is the existing set plus every shallow <oid> minus every unshallow <oid>. A no-op when entries is empty (so a deepen request that reported no boundary change leaves the file untouched). Mirrors git’s update of the shallow file after a deepen fetch.
attach_receive_pack_capabilities: Encode features into the leading ref advertisement’s capability list, inserting a synthetic capabilities^{} entry when there are no refs.
attach_upload_pack_capabilities: Encode features into the leading ref advertisement’s capability list, inserting a synthetic capabilities^{} entry when there are no refs.
build_push_packfile: Build the packfile bytes for a push, excluding objects reachable from remote tips the local repository also holds.
build_receive_pack_body: Build a complete receive-pack push request body: planned commands, negotiated capabilities, optional push-options, and the packfile from build_push_packfile.
clone: Clone the resolved source into a fresh repository at destination.
compute_local_deepen: Compute the deepen plan for a shallow local fetch, mirroring upstream shallow.c::get_shallow_commits: a breadth-first minimum-depth walk from the (tag-dereferenced) heads — the primary planned tips, upload-pack’s want_obj, NOT auto-followed tags — where tips enter at depth 0 and a commit processed at depth d is a boundary commit when d + 1 >= depth (it is packed, but its parents are not walked).
compute_local_deepen_by_rev_list: Deepen plan for the rev-list modes (--shallow-since, --shallow-exclude), mirroring upstream get_shallow_commits_by_rev_list: the kept set is every commit reachable from heads that is newer than since (when given) and not reachable from a deepen_not tip; the boundary is every kept commit with at least one parent outside the kept set.
credential_fill: Fill request (username/password) using the configured credential helpers, returning a complete credential or None if it could not be completed.
credential_request_for_url: The lookup key a credential helper is asked to fill for this remote.
credential_store: Tell the configured helpers to store (approve = true) or erase a credential.
execute_push_action_plan: Execute a previously negotiated exact push plan.
execute_push_plan: Execute a previously planned push.
fetch: Fetch from a resolved source into the repository at git_dir.
fetch_bundle: Fetch from a parsed bundle into the repository at git_dir.
fetch_head_source_description: The FETCH_HEAD source description for source: its configured URL (rewritten per url.<base>.insteadOf) if any, otherwise the rewritten source.
fetch_refspec_excludes: Whether any negative refspec excludes name.
fetch_refspecs_for_source: The effective refspec list for a fetch: explicit refspecs, else the configured remote refspecs, else HEAD; with refs/tags/* appended when fetching all tags.
fetch_source_for_url: Build a FetchSource from a resolved URL.
fetch_url: Resolve the fetch URL for remote using config (name lookup + insteadOf).
git_upload_pack_advertisements
http_advertised_refs: Parse a smart-HTTP info/refs body into a ref advertisement set for protocol v0/v1. Protocol v2 discovery responses require a follow-up ls-refs RPC; use http_service_advertisements instead.
http_authorization_headers: Build the Authorization header list for an optional credential header value.
http_check_status: Map an HTTP response status to success or a descriptive error for url.
http_credential_host: The host[:port] field of a credential request derived from remote.
http_protocol_name: The protocol field of a credential request derived from remote.
http_protocol_v2_fetch_response: Post a protocol v2 fetch RPC with wants/haves/shallow/deepen and read back the sectioned response. Authenticates and validates status + content type. When the server advertises sideband-all, the request and response use the sideband-all wire form.
http_send_with_auth: Perform an HTTP request, retrying once with credential-provider-supplied authentication if the first attempt returns 401. perform is invoked with an optional Authorization header value and must be idempotent (it may run twice). A successful retry approves the credential with credentials; a still-401 retry rejects it.
http_service_advertisements: Fetch and parse the ref advertisements for service from the smart-HTTP info/refs endpoint, authenticating and validating status + content type.
http_upload_pack_advertisements: The upload-pack ref advertisements and parsed features for remote.
http_upload_pack_fetch_response: Post an upload-pack RPC request + haves and read back the raw packfile response, authenticating and validating status + content type. For a plain (non-deepen) request; see http_upload_pack_shallow_fetch_response for the deepen case where the response carries a leading shallow-info section.
http_upload_pack_shallow_fetch_response: Post a deepen upload-pack RPC request + haves and read back the shallow-info section plus the raw packfile response. Use this when request carries a shallow/deepen/deepen-since/deepen-not argument: git always prefixes the response with a shallow-info section (possibly empty) in that case. The returned ProtocolV2FetchShallowInfo entries are the server’s shallow/unshallow updates for $GIT_DIR/shallow.
http_url_credential: Credential implied by user[:password]@ userinfo in the remote URL.
http_validate_content_type: Verify the response Content-Type matches expected (ignoring parameters).
install_fetch_pack_via_git_upload_pack
install_fetch_pack_via_http_protocol_v2_fetch
install_fetch_pack_via_http_upload_pack
install_fetch_pack_via_local_upload_pack: Fetch wants from a local repository at remote_git_dir into the repository at git_dir, round-tripping the request and response through the protocol codecs into the in-process upload-pack so the local path exercises the same wire format as the networked transports. Objects already present locally are skipped; promisor selects promisor-pack installation.
install_fetch_pack_via_ssh_upload_pack
local_fetch_advertisements: The ref advertisements a local repository would send to a fetching client: HEAD (if resolvable) followed by every ref, each resolved to its object id.
local_have_oids: The object ids the local repository can offer as haves during negotiation: the deduplicated tips of its own advertisements.
local_push_source_refs: The push-source refs a local repository can match refspecs against: every ref resolved to its object id, plus the short refs/heads/and refs/tags/ aliases, plus HEAD. Errors if any ref’s object id does not match format.
ls_remote: List the advertised refs for a resolved source.
mark_tag_refspec_updates_not_for_merge: Mark tag refspec updates (refs/tags/X:refs/tags/X) as not-for-merge.
new_http_client: Construct the default HTTP client used for smart-HTTP transport.
normalize_push_refname: Expand a short push ref name to refs/heads/<name>, leaving empty names, HEAD, and already-qualified refs/* names untouched.
normalize_push_refspec: Normalize a push refspec, expanding short names to refs/heads/<name> on both sides and supplying the source as the destination when none is given, while preserving a leading + force marker.
object_format_for_git_dir: The object format of the repository whose common $GIT_DIR is common_git_dir.
order_bundle_fetch_all_tags_updates: Reorder updates so a bundle --tags fetch lists non-tags, then tags pointing at fetched commits, then the remaining tags (matching git’s ordering).
plan_push: Negotiate with the remote and compute the receive-pack command list without sending a pack or applying a ref update.
plan_push_actions: Negotiate with the remote and bind a caller-authored exact push plan to a transport execution token.
prune_remote_tracking_refs_from_advertisements: Prune remote-tracking refs for remote that are absent from advertisements, deleting them and emitting git’s notice lines through progress (unless quiet). Returns the refs that were pruned.
push: Push refspecs to a resolved destination from the repository at git_dir.
push_actions: Push a caller-authored exact plan, preserving its old/new/delete command ids.
push_destination_for_url: Build a PushDestination from a resolved URL.
push_local_with_report: Push to a local repository, returning git’s per-ref status report instead of failing on the first rejection. Performs the client-side checks git’s send-pack does — non-fast-forward and --force-with-lease (stale info) — then (unless --dry-run) sends the surviving commands and folds the receive-pack report-status back into each ref. With --atomic, a single client-side rejection turns every other ref into PushRefStatus::AtomicPushFailed and nothing is sent. The caller renders the report and derives the exit code.
push_url: Resolve the push URL for remote using config (pushurl + pushInsteadOf).
read_shallow: The boundary commit ids recorded in $GIT_DIR/shallow, or an empty vec when the file is absent (a complete repository). Lines are parsed as full hex oids of format; blank lines are ignored.
receive_pack_features: The receive-pack capabilities advertised for a local repository: report status, ref deletion, ofs-delta, push-options, quiet, and the object format.
receive_pack_into_local_repository: Apply a receive-pack push to the repository at remote_git_dir: install the incoming packfile and execute the ref creations/updates/deletions, returning the report-status describing what happened.
receive_pack_request_uses_push_options: Whether the client negotiated push-options (so the caller must read the push-option section that follows the command list).
reject_non_fast_forward_pushes: Reject any non-forced branch update whose old tip is not an ancestor of the new tip (a non-fast-forward). Forced updates, non-branch refs, and creations/deletions are skipped.
remote_advertisement_tips_known_to_local: The advertised tips the local repository already has, deduplicated and excluding the all-zero sentinel — the safe negotiation base for the push pack.
remote_url_is_http: Whether an already-resolved remote url uses HTTP(S) transport.
resolve_fetch_source: Resolve fetch URL rewriting and transport source in one step.
resolve_push_destination: Resolve push URL rewriting and transport destination in one step.
retain_missing_auto_follow_tags: Drop auto-followed tags that already exist locally, keeping only missing ones.
serve_upload_pack_v2: Serve a protocol-v2 upload-pack session over reader/writer for the repository at git_dir. Writes the capability advertisement, then loops reading command= requests (ls-refs / fetch) until the client closes the connection (EOF). Mirrors upload-pack.c::upload_pack_v2 driven by serve.c.
ssh_program: The ssh program to spawn for SSH transport: the GIT_SSH environment variable when set, otherwise ssh. This mirrors git’s basic GIT_SSH selection (the richer GIT_SSH_COMMAND/core.sshCommand forms are not handled, matching the CLI behavior being lifted).
ssh_upload_pack_advertisements: The upload-pack ref advertisements and parsed features for SSH remote.
ssh_upload_pack_fetch_response: Post an upload-pack request + haves over SSH and read back the raw packfile response. The leading re-advertised ref set in the RPC stream is read and discarded before the request is written. For a plain (non-deepen) request; see ssh_upload_pack_shallow_fetch_response for the deepen case.
ssh_upload_pack_shallow_fetch_response: Post a deepen upload-pack request + haves over SSH and read back the shallow-info section plus the raw packfile response. Use this when request carries a shallow/deepen/deepen-since/deepen-not argument: the response is then prefixed with a shallow-info section (possibly empty). The returned ProtocolV2FetchShallowInfo entries are the server’s shallow-info updates.
transport_kind_for_url: Classify a rewritten URL for capability checks.
upload_pack_features: The upload-pack capabilities advertised for the repository at git_dir: the object format, side-band-64k, and a HEAD symref hint if present.
upload_pack_from_local_repository: Serve an upload-pack request from the repository at git_dir: build the packfile that carries every reachable object the client wants but does not already haves, framed as a raw (non-side-band) response.
upload_pack_request_uses_sideband: Whether the client negotiated a side-band channel for the packfile response.
upload_pack_sideband_response: Re-frame a raw packfile response as side-band data packets, chunked to the pkt-line payload limit (less the one-byte channel prefix).
validate_receive_pack_report: Validate a receive-pack report-status, surfacing a failed unpack or any rejected ref as an error (matching git’s exit-failure message form).
write_default_fetch_head: Write a single default FETCH_HEAD record (a bare HEAD fetch).
write_fetch_head: Write FETCH_HEAD from fetched ref updates, describing each by description.
write_fetch_head_records: Write FETCH_HEAD records, truncating or appending per append.
write_shallow: Write $GIT_DIR/shallow from oids, sorting and de-duplicating them the way git does (by hex, one per line, trailing newline). An empty set removes the file so the repository reads as complete.