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.
PruneRefsInput: Prune refs whose destinations are covered by the active fetch refspecs and whose corresponding remote sources are absent from advertisements, deleting them and emitting git’s notice lines through progress (unless quiet). Returns the refs that were pruned.
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.
SshTransportOptions
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.
TransportPolicyError

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.
check_transport_allowed
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
git_upload_pack_advertisements_with_protocol
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
is_transport_allowed
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. Ref tips are offered first, then every object visible through the local object database, including alternates recorded in objects/info/alternates.
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_refs_from_advertisements
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.
serve_upload_pack_v2_with_config
ssh_program: The ssh program to spawn for SSH transport: GIT_SSH_COMMAND’s first shell word, then GIT_SSH, then ssh.
ssh_transport_options_from_config
ssh_upload_pack_advertisements: The upload-pack ref advertisements and parsed features for SSH remote.
ssh_upload_pack_advertisements_with_options
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.
transport_scheme_for_remote
transport_scheme_for_url: Classify the policy protocol name for a raw transport URL.
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.