girt 0.18.0

//! Clone repositories, fetch from, push to and query configured remotes.
//!
//! Most applications that talk to Git remotes want the behavior a Git user already expects: name a
//! remote such as `origin`, and let the repository's configuration decide the URL, the transport,
//! the credentials and the proxy. This module provides synchronous transfer functions:
//!
//! - [`clone()`] creates a repository and checks out its default branch; [`clone_with`] selects
//!   policy.
//! - [`fetch`] downloads objects and updates remote-tracking references and tags.
//! - [`push`] conditionally updates references on the remote.
//! - [`remote_head`] asks which branch the remote's `HEAD` names, as a clone does.
//! - [`fetch_missing`] and [`fetch_promised`] fetch objects a partial clone lacks. Reading an
//!   object never fetches it; these are the explicit, batched alternative to Git's lazy fetch.
//!
//! Fetch, push and remote-head queries take the [`Repository`] explicitly, an [`Environment`]
//! snapshot instead of reading the process environment, and a [`TransferCallbacks`] implementation
//! for progress and credential prompts. They return typed reports, never printed text.
//!
//! [`crate::Repo`] owns a repository and composes these transfers with Git defaults and a captured
//! environment for trusted local use. Use [`Repository`] and these functions directly when callers
//! need to select transfer options, callbacks, or environment explicitly.
//!
//! # Quick start
//!
//! Create a repository, add a remote to its configuration, then fetch from it. In this example
//! `origin` is a local repository path, so the example runs without a network; an `https://` or
//! `ssh://` URL takes the same code path once the `http` or `ssh` feature is enabled.
//!
//! ```
//! use girt::refs::{RefName, Target};
//! use girt::remote::RemoteConfig;
//! use girt::workflow::{self, Environment, FetchOptions, NoCallbacks};
//! use girt::{InitKind, ObjectFormat, Repository};
//!
//! // `directory` already holds `upstream.git`, a repository whose `main` branch points to the
//! // commit `main` (setup hidden).
//! # let (directory, _, _, main, _) = include!("doctest/remote.rs");
//! let path = directory.path().join("project");
//! Repository::init(ObjectFormat::Sha1, &path, InitKind::Worktree)?;
//!
//! // Record the remote in the repository's own config file, as `git remote add` would.
//! let mut edit = Repository::open(&path)?.edit_config(1 << 20)?;
//! RemoteConfig::new(edit.document_mut()).add(
//!     b"origin",
//!     b"../upstream.git",
//!     &[b"+refs/heads/*:refs/remotes/origin/*"],
//! )?;
//! edit.commit()?;
//!
//! // A `Repository` holds a configuration snapshot, so reopen it to see the new remote.
//! let repo = Repository::open(&path)?;
//! let options = FetchOptions::new(["+refs/heads/*:refs/remotes/origin/*"]);
//! // Applications usually pass `Environment::from_process()`. An empty environment keeps this
//! // example independent of the caller's settings, and makes the relative URL resolve against
//! // the working tree.
//! let outcome = workflow::fetch(
//!     &repo,
//!     "origin",
//!     &options,
//!     &Environment::default(),
//!     &mut NoCallbacks,
//! )?;
//!
//! let tracking = RefName::new("refs/remotes/origin/main")?;
//! assert_eq!(outcome.updated.len(), 1);
//! assert_eq!(outcome.updated[0].name, tracking);
//! assert_eq!(
//!     repo.references()?.read(&tracking)?,
//!     Some(Target::Direct(main))
//! );
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! # Choosing between `workflow` and the core transfer APIs
//!
//! girt has two layers for moving objects between repositories. This module is the convenience
//! layer. The core layer, [`crate::fetch`], [`crate::push`] and [`crate::clone`], makes every
//! decision explicit: which endpoint, which resource limits, which credentials, when to install
//! objects and when to publish references. Use this module when:
//!
//! - the remote is named in the repository's configuration and should be resolved as Git resolves
//!   it;
//! - the remote is trusted the way a Git user trusts their own remotes (see [Limits and
//!   trust](#limits-and-trust));
//! - the caller can block a thread for the whole transfer and does not need to cancel it.
//!
//! Use the core APIs instead when the endpoint comes from somewhere other than configuration, when
//! the peer is untrusted and transfers must be bounded, when the caller needs cancellation or a
//! deadline, or when downloads should be validated on a separate worker pool. The core APIs also
//! cover operations this module does not, such as retaining a fetched pack against repacking while
//! the caller checks it before publishing references, or publishing shallow boundaries under caller
//! control. Depth-limited fetches themselves are supported here through
//! [`FetchOptions::with_depth`], and partial fetches through [`FetchOptions::with_filter`].
//!
//! # What a configured transfer does
//!
//! Configured transfers choose a transport and authenticate the same way:
//!
//! 1. **Resolve the remote.** The named remote's `url` (or, for [`push`], its first `pushurl`) is
//!    read from [`Repository::config`] and rewritten by `url.<base>.insteadOf` and `pushInsteadOf`.
//!    `protocol.allow`, `protocol.<name>.allow` and `GIT_ALLOW_PROTOCOL` decide whether the
//!    resulting transport may be used. See [`crate::remote::Remote::fetch_destination`] and
//!    [`crate::remote::Remote::push_destinations`].
//! 2. **Choose a transport** from the URL. Local paths and `file://` URLs use girt's native local transfer,
//!    which reads and writes the other repository's storage directly and never starts Git. `http://`
//!    and `https://` need the `http` feature; `ssh://` and `user@host:path` need the `ssh` feature
//!    on macOS or Linux. Any other scheme, such as `mem://repo` or `vault::team/project`, uses the
//!    application's [`Transport`](crate::transport::Transport) from
//!    [`TransferCallbacks::transport`], for listing, fetch, clone and push; without one, and for
//!    `git://`, the result is [`TransferError::UnsupportedTransport`].
//! 3. **Authenticate if asked.** An HTTP server that answers `401 Unauthorized` gets one retry with
//!    a credential. Configured `credential.helper` programs are asked first; Git's `store` helper
//!    is answered natively by [`crate::remote::CredentialStore`]. If no helper supplies a value,
//!    the askpass program from `GIT_ASKPASS`, `core.askPass` or `SSH_ASKPASS` is asked, as Git
//!    does, and then [`TransferCallbacks::credential`] for the username and password. A credential
//!    the server accepts is reported to the helpers for storage; a rejected one is reported for
//!    removal. SSH authentication is left to OpenSSH and the user's SSH configuration, agent and
//!    `SSH_ASKPASS` program, all taken from the [`Environment`].
//!
//! [`remote_head`] then reads the reference advertisement and stops. [`fetch`] continues:
//!
//! 4. **Negotiate.** Local reference tips are offered as history the repository already has, so the
//!    server can leave those objects out. HTTP and SSH ask for the upload-pack protocol named by
//!    `protocol.version` (v2 when unset, as Git does) and accept a v0 or v1 answer.
//! 5. **Validate and install.** Every received object's framing, delta chain and identity are
//!    checked, and the new history of every selected tip, down to history the repository already
//!    has, is walked to check that it is complete and well-formed, before the pack is installed.
//! 6. **Publish.** First every planned change is checked against its refspec's rules, such as
//!    fast-forwarding; if any check fails, no reference changes. Then stale references are pruned
//!    in one transaction and the remaining references updated in a second, each conditional on the
//!    values seen before the transfer. A reference another process moved meanwhile is never
//!    overwritten, but that conflict can be detected after pruning has already happened, and an I/O
//!    failure can leave some references updated. The error reports what was published.
//!
//! [`push`] instead reads the remote's advertisement, sends a pack without the history the remote
//! already has, and lets the remote check each command's expected value. Commands succeed or fail
//! independently. Afterwards it updates the matching local remote-tracking references
//! unconditionally, as a best effort that a later fetch corrects.
//!
//! # Concurrency
//!
//! Other processes may update references in either repository during a transfer: fetch publishes
//! only if its destinations still have the values it started from, and the remote checks every
//! push command the same way. Reference locks do not protect everything, though. From the start
//! of a [`fetch`] until it returns, the caller must keep these from running in the local
//! repository, and for a [`push`] to a local path, in the destination too:
//!
//! - garbage collection or pruning, which could delete objects the transfer depends on;
//! - checkout, or changes to `HEAD` and which branch a worktree has checked out;
//! - adding or removing linked worktrees.
//!
//! [`crate::fetch::FetchRequest`] and [`crate::push::send_local`] document the full contract.
//!
//! # Limits and trust
//!
//! A Git client trusts the remotes its user configured: `git fetch` imposes no limit on how large a
//! pack, an object or an advertisement may be. This module follows Git and uses
//! [`FetchLimits::trusted`], [`crate::push::PushLimits::trusted`] and
//! [`crate::PackLimits::trusted`]. Validation is never relaxed. A trusted transfer still rejects
//! malformed, corrupt or disconnected data. What trust removes is the ceiling on how much
//! *well-formed* work a peer can ask for. A hostile server could send a multi-gigabyte pack or a
//! deeply nested delta chain, and the transfer would only stop when it ran out of disk, memory or
//! time.
//!
//! Clone instead uses bounded default limits; [`CloneOptions`] makes its bounds explicit.
//!
//! When the remote is chosen by someone other than the local user, for example a service that
//! fetches URLs submitted by its users, do not use this module. Call the core APIs with
//! [`FetchLimits::default`], which bounds wire bytes, pack size, object count, per-object size,
//! delta depth and decoding work, and set a deadline with
//! [`TransportControl::with_deadline`](crate::transport::TransportControl::with_deadline).
//! [`crate::fetch::FetchLimits`] documents each bound and the defaults.
//!
//! # Threads, runtimes and cancellation
//!
//! Every function blocks the calling thread until the transfer finishes. HTTP and SSH transfers
//! create a private single-threaded Tokio runtime for the duration of the call, so these functions
//! must not be called from a thread that is already running a Tokio runtime: Tokio panics when a
//! runtime is started inside another. From async code, move the call to a blocking thread with
//! `tokio::task::spawn_blocking`. Local transfers start no runtime.
//!
//! Callbacks run on the calling thread, in order. A transfer cannot be cancelled and has no
//! deadline; a stalled HTTP server or SSH connection blocks until the operating system or the peer
//! gives up. Applications that need either use the core APIs, which take a [`TransportControl`].
//!
//! # Errors
//!
//! Fetch, push and remote-head queries return [`TransferError`]. Its variants say how far the
//! operation got:
//!
//! | Variant | Local changes | What to do |
//! | --- | --- | --- |
//! | [`NoSuchRemote`](TransferError::NoSuchRemote) | none | Check the name or add the remote. |
//! | [`Configuration`](TransferError::Configuration) | none | Report it; the user's config is invalid or unsupported. |
//! | [`UnsupportedTransport`](TransferError::UnsupportedTransport) | none | Enable the feature, register a transport or use another URL. |
//! | [`Transport`](TransferError::Transport) | none | Inspect the application transport's error. |
//! | [`Authentication`](TransferError::Authentication) | none | Ask for a different credential. |
//! | [`Fetch`](TransferError::Fetch) | none | Inspect the cause; retrying is safe. |
//! | [`FetchFinish`](TransferError::FetchFinish) | objects, shallow boundaries or some references, depending on the phase | Inspect the report; fetching again is safe. |
//! | [`Push`](TransferError::Push) | none locally | If [`Uncertain`](crate::push::PushError::Uncertain), read the remote's references before retrying. |
//! | [`Local`](TransferError::Local) | none | Reading this repository failed. |
//! | [`NotPromisor`](TransferError::NotPromisor), [`NoPromisorRemote`](TransferError::NoPromisorRemote) | none | Ask a promisor remote; see [`promisor_remotes`]. |
//! | [`NotFetched`](TransferError::NotFetched) | the objects the remote did send | Ask another promisor remote. |
//!
//! Clone returns [`CloneError`], preserving destination creation and checkout reports as well as
//! transfer errors.
//!
//! A successful [`push`] can still contain rejected references: check
//! [`PushReport::all_succeeded`](crate::push::PushReport::all_succeeded) or each
//! [`RefStatus`](crate::push::RefStatus).
//!
//! # How jj uses this module
//!
//! [jj](https://github.com/jj-vcs/jj)'s experimental girt backend uses this module for every Git
//! remote operation. Its adapter is a useful model for other version-control front ends:
//!
//! - It captures [`Environment::from_process`] once and layers jj's own overrides on top with
//!   [`Environment::with`], so tests and subprocesses see exactly the variables jj chose.
//! - `jj git fetch` builds [`FetchOptions`] from the user's branch patterns, including negative
//!   `^refs/heads/…` refspecs, and always enables [`FetchOptions::with_prune`]. It passes the
//!   requested [`FetchOptions::with_depth`], records reflog entries with
//!   [`FetchOptions::with_reflog`], and keeps per-remote tags in a
//!   [`FetchOptions::with_tag_namespace`]. Branches named exactly but absent on the remote arrive
//!   in [`FetchOutcome::missing_sources`] and are logged rather than failing the fetch.
//! - After a fetch, jj reopens its [`Repository`] and object store. An open
//!   [`Objects`](crate::Objects) reader keeps the pack list it started with, so it cannot see the
//!   pack the fetch just installed.
//! - jj finds a remote's default branch with [`remote_head`]. Only [`RemoteHead::Symbolic`] and
//!   [`RemoteHead::Inferred`] name one; every other answer means "no default branch".
//! - `jj git push` sends one [`PushCommand`] per bookmark, with the remote value jj last saw as
//!   `expected` and [`ForcePolicy::Allow`](crate::push::ForcePolicy::Allow). That is Git's
//!   `--force-with-lease`: jj may move a bookmark sideways, but only if nobody else moved it first.
//!   A rejection with
//!   [`RejectionOrigin::ExpectedValue`](crate::push::RejectionOrigin::ExpectedValue) becomes jj's
//!   "stale info" message.
//! - Its [`TransferCallbacks`] splits [`TransferCallbacks::remote_message`] bytes into lines at
//!   `\r` and `\n`, parses `Counting objects:` lines into a progress bar, forwards SSH diagnostics
//!   from [`TransferCallbacks::transport_message`] to the terminal, and answers
//!   [`TransferCallbacks::credential`] with jj's own prompt.
//!
//! # Platform and feature support
//!
//! Local paths always work. HTTP(S) needs the `http` feature. SSH needs the `ssh` feature and runs
//! the system OpenSSH client, on macOS and Linux only. See [`crate::transport`] for each
//! transport's configuration support and limitations.

#![warn(
    clippy::unwrap_used,
    clippy::expect_used,
    clippy::panic,
    clippy::unreachable,
    clippy::indexing_slicing,
    reason = "parses untrusted repository or network input (#103)"
)]

use std::collections::{BTreeMap, BTreeSet};
use std::ffi::{OsStr, OsString};
use std::num::NonZeroU32;
use std::ops::ControlFlow;
use std::path::{Path, PathBuf};
use std::sync::atomic::AtomicBool;

use crate::fetch::{
    FetchLimits, FetchRequest, FetchUpdateKind, FetchUpdateLimits, FetchWorkflowError,
    KnownHistory, ObjectFilter, RemoteHead,
};
use crate::push::{PreparedPush, PushCommand, PushFailure, PushLimits, PushReport};
use crate::refs::{RefName, Reflog};
use crate::remote::{Destination, Direction, Protocol, ProtocolEnvironment, Refspecs, Remote};
use crate::repository::{CONVENTIONAL, ReflogScope};
use crate::transport::TransportControl;
use crate::{ObjectId, Repository};

mod clone;
pub use clone::{CloneError, CloneOptions, CloneOutcome, clone, clone_with};
mod missing;
pub use missing::{PromisorFetch, fetch_missing, fetch_needed, fetch_promised, promisor_remotes};

/// Asks a configured remote which branch its `HEAD` names, without downloading objects.
///
/// This is how a client learns a remote's default branch, for example to choose what to check
/// out after a clone or which bookmark to track. Only the reference advertisement is read: no
/// objects are transferred and the local repository is not changed. The remote is resolved,
/// authenticated and reached exactly as by [`fetch`].
///
/// The answer is a snapshot. The remote's `HEAD` can change before any later fetch, so don't use
/// it as a precondition for updating references.
///
/// # Interpreting the answer
///
/// Servers that send a symbolic `HEAD` hint (all modern Git servers, and every local repository)
/// produce [`RemoteHead::Symbolic`], or [`RemoteHead::Unborn`] for an empty repository whose
/// default branch has no commits yet. Older servers advertise only `HEAD`'s object ID; girt then
/// reports [`RemoteHead::Inferred`] when exactly one branch has that ID, and
/// [`RemoteHead::Ambiguous`] or [`RemoteHead::Detached`] otherwise. It never guesses.
///
/// # Examples
///
/// ```
/// use girt::fetch::RemoteHead;
/// use girt::workflow::{self, Environment, NoCallbacks};
/// # let (_directory, _, repo, main, _) = include!("doctest/remote.rs");
///
/// // `repo` has a remote `origin` whose `HEAD` names `main`.
/// let head = workflow::remote_head(&repo, "origin", &Environment::default(), &mut NoCallbacks)?;
/// let default_branch = match head {
///     RemoteHead::Symbolic { branch, id } => {
///         assert_eq!(id, main);
///         Some(branch)
///     }
///     RemoteHead::Inferred { branch, .. } => Some(branch),
///     // An empty remote, a detached HEAD or an ambiguous answer has no default branch.
///     _ => None,
/// };
///
/// assert_eq!(
///     default_branch,
///     Some(girt::refs::RefName::new("refs/heads/main")?)
/// );
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
///
/// # Errors
///
/// Returns [`TransferError`] when the remote is missing or misconfigured, its transport is
/// unsupported, authentication fails, or the advertisement cannot be read. A failed query changes
/// nothing.
pub fn remote_head(
    repository: &Repository,
    remote_name: &str,
    environment: &Environment,
    callbacks: &mut dyn TransferCallbacks,
) -> Result<RemoteHead, TransferError> {
    repository.remote_head(remote_name, environment, callbacks)
}

/// Lists a configured remote's references, as `git ls-remote <remote>` does.
///
/// The remote is resolved, authenticated and configured exactly as for [`fetch`]: URL rewrites,
/// protocol policy, `http.*` settings, credential helpers, askpass and
/// [`TransferCallbacks::credential`]. Nothing is downloaded and nothing changes locally. The
/// result holds every advertised reference with its peeled tag hints, the object format, the
/// interpreted `HEAD` and the protocol version.
///
/// # Examples
///
/// ```
/// use girt::workflow::{self, Environment, NoCallbacks};
/// # let (_directory, _, repo, main, _) = include!("doctest/remote.rs");
///
/// // `repo` has a remote `origin` whose `main` branch points at `main`.
/// let listing =
///     workflow::remote_refs(&repo, "origin", &Environment::default(), &mut NoCallbacks)?;
/// assert!(listing.advertisement.refs.iter().any(|reference| {
///     reference.name.as_bytes() == b"refs/heads/main" && reference.id == main
/// }));
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
///
/// # Errors
///
/// Returns the errors from [`remote_head`].
pub fn remote_refs(
    repository: &Repository,
    remote_name: &str,
    environment: &Environment,
    callbacks: &mut dyn TransferCallbacks,
) -> Result<crate::fetch::RemoteDiscovery, TransferError> {
    repository.discover_remote(remote_name, environment, callbacks)
}

/// Downloads objects from a configured remote and updates local references to match.
///
/// The refspecs in `options` choose which remote references to fetch and where to record them,
/// exactly as on the `git fetch` command line; the remote's configured `fetch` refspecs are not
/// added. A typical call passes the remote's configured refspecs, such as
/// `+refs/heads/*:refs/remotes/origin/*`.
///
/// Objects are validated and installed before any reference moves. Every planned change is then
/// checked against its refspec's rules; if one fails, no reference changes. Pruned references
/// are deleted in one transaction and the other changes applied in a second, each requiring the
/// destination to still have the value it had when the fetch began, so a reference moved by
/// another process during the transfer is never overwritten. Because the transactions are
/// separate, a conflict in the second can be reported after pruning has happened.
///
/// # What is and isn't updated
///
/// Destinations must be remote-tracking references (`refs/remotes/…`), tags (`refs/tags/…`), or
/// references below a namespace allowed with [`FetchOptions::with_tag_namespace`]. Local branches
/// are never fetch destinations, so a fetch cannot move the branch a working tree has checked out.
/// Without a `+` prefix, a remote-tracking reference whose old and new values are both commits
/// may only fast-forward, and an existing tag may not change; either violation fails the fetch
/// without updating any reference. A remote-tracking reference pointing to another kind of object,
/// such as a tree, can be replaced without `+`.
///
/// Unlike `git fetch`, no `FETCH_HEAD` is written and tags pointing into fetched history are not
/// followed automatically: name the tags you want with a refspec such as
/// `refs/tags/*:refs/tags/*`. Exact (non-glob) sources the remote doesn't have are reported in
/// [`FetchOutcome::missing_sources`] rather than failing the fetch.
///
/// Afterwards, like `git fetch`, this runs Git's automatic pack-refs task (see
/// [`Repository::auto_pack_references`]). A failure there does not fail the fetch. Disable this
/// optional work with [`FetchOptions::with_auto_pack_refs`] when composing bounded maintenance.
///
/// The repository's open [`Objects`](crate::Objects) readers keep their earlier pack list. Open a
/// new reader, or reopen the repository, to read the fetched objects.
///
/// # Examples
///
/// Fetch every branch of `origin` into `refs/remotes/origin/`:
///
/// ```
/// use girt::refs::{RefName, Target};
/// use girt::workflow::{self, Environment, FetchOptions, NoCallbacks};
/// # let (_directory, _, repo, main, _) = include!("doctest/remote.rs");
///
/// let options = FetchOptions::new(["+refs/heads/*:refs/remotes/origin/*"]);
/// let outcome = workflow::fetch(
///     &repo,
///     "origin",
///     &options,
///     &Environment::default(),
///     &mut NoCallbacks,
/// )?;
///
/// for update in &outcome.updated {
///     // Reference names are bytes, like Git's; they need not be UTF-8.
///     let name = String::from_utf8_lossy(update.name.as_bytes());
///     println!("{name}: {:?} -> {:?}", update.old, update.new);
/// }
///
/// let tracking = RefName::new("refs/remotes/origin/main")?;
/// assert_eq!(
///     repo.references()?.read(&tracking)?,
///     Some(Target::Direct(main))
/// );
///
/// // Nothing changed upstream, so a second fetch transfers nothing and updates nothing.
/// let again = workflow::fetch(
///     &repo,
///     "origin",
///     &options,
///     &Environment::default(),
///     &mut NoCallbacks,
/// )?;
/// assert!(again.updated.is_empty());
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
///
/// # Errors
///
/// Returns [`TransferError`]. Every variant except [`TransferError::FetchFinish`] means no local
/// change was made. `FetchFinish` means the pack was received and validated, but installing it or
/// publishing the results failed partway. Its [`FetchFinishError`](crate::fetch::FetchFinishError)
/// says how far it got: `report.installed` is set only if the pack was installed,
/// `report.shallow_published` if `.git/shallow` changed, and the failure carries any partial
/// reference effects. Fetching again is safe in every case.
pub fn fetch(
    repository: &Repository,
    remote_name: &str,
    options: &FetchOptions,
    environment: &Environment,
    callbacks: &mut dyn TransferCallbacks,
) -> Result<FetchOutcome, TransferError> {
    repository.fetch(remote_name, options, environment, callbacks)
}

/// Sends objects to a configured remote and conditionally updates its references.
///
/// Each [`PushCommand`] names a remote reference, the value the caller believes it has
/// (`expected`, or `None` for "must not exist"), and the new value (the null ID deletes it). The
/// remote applies a command only if the reference still has the expected value. This is Git's
/// `--force-with-lease` with an explicit lease, and it is always on: girt has no unconditional
/// push. [`ForcePolicy`](crate::push::ForcePolicy) separately decides whether a branch may move
/// to a commit that does not descend from its old value.
///
/// Commands succeed or fail independently. A successful return means the remote answered, not
/// that every update was applied; check [`PushReport::all_succeeded`] or each
/// [`RefStatus`](crate::push::RefStatus).
///
/// Like `git push`, the pack omits history reachable from anything the remote advertises, so
/// creating a branch sends only the commits the remote lacks. The pack is prepared after the
/// advertisement is read, while the connection is open. If a local remote's references change
/// during preparation, the push is prepared again once against the new references.
///
/// After a successful update, the matching remote-tracking reference (found through the remote's
/// `fetch` refspecs) is updated locally as `git push` does. Failures there are ignored; the next
/// fetch corrects them.
///
/// Only the remote's first push URL is used. Git pushes to every configured `pushurl`; to do the
/// same, configure one remote per URL. Atomic and signed pushes are unsupported. A local
/// destination's `receive.denyCurrentBranch` is honored as Git honors it, so by default a branch
/// checked out in the destination's working tree is refused. With `updateInstead` on macOS and
/// Linux, a clean working tree is updated to the pushed commit before the branch moves, and a tree
/// with staged or unstaged changes refuses that reference, as with Git.
///
/// # Examples
///
/// Publish a new branch on `origin`. `expected: None` means the push is rejected if someone else
/// created the branch first with a different commit:
///
/// ```
/// use girt::push::{ForcePolicy, PushCommand};
/// use girt::refs::{RefName, Target};
/// use girt::workflow::{self, Environment, FetchOptions, NoCallbacks, PushOptions};
/// # let (_directory, upstream, repo, main, person) = include!("doctest/remote.rs");
/// let environment = Environment::default();
///
/// // Fetch first, so the commit to publish exists locally.
/// let options = FetchOptions::new(["+refs/heads/*:refs/remotes/origin/*"]);
/// workflow::fetch(&repo, "origin", &options, &environment, &mut NoCallbacks)?;
///
/// let topic = RefName::new("refs/heads/topic")?;
/// let command =
///     PushCommand::new(topic.clone(), None, main).with_force(ForcePolicy::FastForwardOnly);
/// let report = workflow::push(
///     &repo,
///     "origin",
///     vec![command],
///     &PushOptions::default().with_identity(person),
///     &environment,
///     &mut NoCallbacks,
/// )?;
///
/// assert!(report.all_succeeded(), "rejected: {report:?}");
/// assert_eq!(
///     upstream.references()?.read(&topic)?,
///     Some(Target::Direct(main))
/// );
///
/// // The local remote-tracking reference now records the pushed value.
/// let tracking = RefName::new("refs/remotes/origin/topic")?;
/// assert_eq!(
///     repo.references()?.read(&tracking)?,
///     Some(Target::Direct(main))
/// );
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
///
/// A stale expectation is reported per reference rather than as an error:
///
/// ```
/// use girt::push::{ForcePolicy, PushCommand, RejectionOrigin, Status};
/// use girt::refs::RefName;
/// use girt::workflow::{self, Environment, NoCallbacks, PushOptions};
/// use girt::{ObjectFormat, ObjectId, ObjectKind};
/// # let (_directory, upstream, repo, main, _) = include!("doctest/remote.rs");
/// # let environment = Environment::default();
///
/// // Try to delete `main` on `origin`, believing it points to a commit it doesn't point to.
/// let believed = ObjectFormat::Sha1.hash_object(ObjectKind::Commit, b"an outdated view");
/// let delete = ObjectId::null(ObjectFormat::Sha1);
/// let command = PushCommand::new(RefName::new("refs/heads/main")?, Some(believed), delete)
///     .with_force(ForcePolicy::Allow);
/// let report = workflow::push(
///     &repo,
///     "origin",
///     vec![command],
///     &PushOptions::default(),
///     &environment,
///     &mut NoCallbacks,
/// )?;
///
/// assert!(!report.all_succeeded());
/// assert!(matches!(report.refs[0].status, Some(Status::Rejected(_))));
/// assert_eq!(
///     report.refs[0].rejection_origin,
///     Some(RejectionOrigin::ExpectedValue)
/// );
/// # assert!(upstream.references()?.read(&RefName::new("refs/heads/main")?)?.is_some());
/// # let _ = main;
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
///
/// # Errors
///
/// Returns [`TransferError::Push`] when the push could not complete. The boxed
/// [`PushError`](crate::push::PushError) says whether the remote may have been changed:
/// [`NotSent`](crate::push::PushError::NotSent) guarantees no command reached it, while
/// [`Uncertain`](crate::push::PushError::Uncertain) means some updates may have been applied.
/// After an uncertain failure, read the remote's references (for example with a fetch) before
/// pushing again. Other variants fail before any data is sent.
pub fn push(
    repository: &Repository,
    remote_name: &str,
    commands: Vec<PushCommand>,
    options: &PushOptions,
    environment: &Environment,
    callbacks: &mut dyn TransferCallbacks,
) -> Result<PushReport, TransferError> {
    repository.push(remote_name, commands, options, environment, callbacks)
}

/// The environment variables and working directory a transfer may consult.
///
/// Git's transfer behavior depends on process state: `GIT_SSH_COMMAND` selects the SSH client,
/// `https_proxy` and `no_proxy` choose a proxy, `GIT_SSL_CAINFO` replaces trusted certificates,
/// `GIT_ALLOW_PROTOCOL` restricts transports, `HOME` and `XDG_CONFIG_HOME` locate the credential
/// store, and `PATH` finds `ssh` and `git-credential-*` helpers. The functions in this module never
/// read the process environment themselves. They consult only this snapshot, and child processes
/// (SSH and credential helpers) receive exactly these variables.
///
/// That makes behavior reproducible and testable: a test can pass an environment with a private
/// `HOME`, and a server can run transfers for several users with different settings in one
/// process. Most applications start from [`Environment::from_process`] and adjust it.
///
/// The [`Debug`] output lists variable names only, because values such as proxy URLs can contain
/// credentials.
///
/// # Examples
///
/// ```
/// use std::ffi::OsStr;
///
/// use girt::workflow::Environment;
///
/// // Start from this process and route SSH through a specific key, as `GIT_SSH_COMMAND` would.
/// let environment = Environment::from_process()
///     .with("GIT_SSH_COMMAND", "ssh -i ~/.ssh/deploy_key")
///     .without("GIT_ALLOW_PROTOCOL");
/// assert_eq!(
///     environment.get("GIT_SSH_COMMAND"),
///     Some(OsStr::new("ssh -i ~/.ssh/deploy_key"))
/// );
/// assert_eq!(environment.get("GIT_ALLOW_PROTOCOL"), None);
///
/// // Or build a fully controlled environment, for example in a test.
/// let isolated: Environment = [("HOME", "/nonexistent"), ("PATH", "/usr/bin:/bin")]
///     .into_iter()
///     .collect();
/// assert_eq!(isolated.get("HOME"), Some(OsStr::new("/nonexistent")));
/// assert_eq!(isolated.get("USER"), None);
/// ```
#[derive(Clone, Default)]
pub struct Environment {
    vars: BTreeMap<OsString, OsString>,
    current_dir: Option<PathBuf>,
}

impl std::fmt::Debug for Environment {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // Values can contain secrets such as tokens.
        f.debug_struct("Environment")
            .field("names", &self.vars.keys().collect::<Vec<_>>())
            .finish()
    }
}

impl Environment {
    /// Captures the current process's environment variables and working directory.
    ///
    /// This is the usual starting point; the result behaves as `git` would when started from this
    /// process. The snapshot is taken once: later changes to the process environment do not
    /// affect it. If the working directory cannot be read (for example because it was deleted),
    /// relative local remote paths resolve against the repository instead; see
    /// [`Self::with_current_dir`].
    pub fn from_process() -> Self {
        let mut environment: Self = std::env::vars_os().collect();
        environment.current_dir = std::env::current_dir().ok();
        environment
    }

    /// Sets the directory that relative local remote paths are resolved against.
    ///
    /// Git resolves a remote URL such as `../upstream.git` against its working directory. Without
    /// a current directory (for example an environment built with [`FromIterator`]), relative paths
    /// resolve against the repository's working tree, or its Git directory if it is bare. A
    /// relative `credential.helper=store --file` path resolves against this directory as well.
    ///
    /// # Examples
    ///
    /// ```
    /// use girt::workflow::{self, Environment, NoCallbacks};
    /// # use girt::remote::RemoteConfig;
    /// # let (directory, _, repo, main, _) = include!("doctest/remote.rs");
    /// # let mut edit = repo.edit_config(1 << 20)?;
    /// # RemoteConfig::new(edit.document_mut()).add(b"relative", b"upstream.git", &[])?;
    /// # edit.commit()?;
    /// # let repo = girt::Repository::open(directory.path().join("local"))?;
    ///
    /// // `repo` has a remote `relative` whose URL is the relative path `upstream.git`.
    /// let environment = Environment::default().with_current_dir(directory.path());
    /// let head = workflow::remote_head(&repo, "relative", &environment, &mut NoCallbacks)?;
    /// assert!(matches!(head, girt::fetch::RemoteHead::Symbolic { id, .. } if id == main));
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn with_current_dir(mut self, directory: impl Into<PathBuf>) -> Self {
        self.current_dir = Some(directory.into());
        self
    }

    /// Returns a variable's value, or `None` if it is not set.
    ///
    /// Names are compared exactly, including case, on every platform.
    pub fn get(&self, name: &str) -> Option<&OsStr> {
        self.vars.get(OsStr::new(name)).map(OsString::as_os_str)
    }

    /// Sets a variable, replacing any previous value, and returns `self` for chaining.
    pub fn with(mut self, name: impl Into<OsString>, value: impl Into<OsString>) -> Self {
        self.vars.insert(name.into(), value.into());
        self
    }

    /// Removes a variable, if set, and returns `self` for chaining.
    ///
    /// Removing a variable makes the transfer behave as if it were never set, which is different
    /// from setting it to an empty value: an empty `GIT_ALLOW_PROTOCOL` allows no protocols.
    pub fn without(mut self, name: impl AsRef<OsStr>) -> Self {
        self.vars.remove(name.as_ref());
        self
    }

    /// Every variable, for starting a child process with exactly this environment.
    pub(crate) fn vars(&self) -> impl Iterator<Item = (&OsStr, &OsStr)> {
        self.vars
            .iter()
            .map(|(name, value)| (name.as_os_str(), value.as_os_str()))
    }

    /// The directory relative paths resolve against, if known.
    pub(crate) fn current_dir(&self) -> Option<&std::path::Path> {
        self.current_dir.as_deref()
    }

    fn bytes(&self, name: &str) -> Option<Vec<u8>> {
        self.get(name)
            .map(|value| value.as_encoded_bytes().to_vec())
    }

    #[cfg(feature = "http")]
    fn string(&self, name: &str) -> Option<String> {
        self.get(name).and_then(OsStr::to_str).map(str::to_owned)
    }
}

impl<K: Into<OsString>, V: Into<OsString>> FromIterator<(K, V)> for Environment {
    fn from_iter<I: IntoIterator<Item = (K, V)>>(iter: I) -> Self {
        Self {
            vars: iter
                .into_iter()
                .map(|(name, value)| (name.into(), value.into()))
                .collect(),
            current_dir: None,
        }
    }
}

/// Which part of a credential [`TransferCallbacks::credential`] is asking for.
///
/// An HTTP transfer asks for the username first, unless a credential helper or the
/// `credential.username` setting already supplied one, then the password. A personal access token
/// is usually supplied as the password. The enum is non-exhaustive: return `None` for prompts the
/// application does not recognize.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum CredentialPrompt {
    /// The username for the URL.
    Username,
    /// The password or token for the URL.
    Password,
}

/// Receives progress and diagnostics during a transfer, and answers credential prompts.
///
/// A command-line client shows the remote's progress messages, SSH warnings and a password prompt;
/// a GUI or service needs the same information in its own form. Implement the methods you need:
/// every method has a default that ignores its input or declines to answer. Use [`NoCallbacks`]
/// when nothing should be shown and no prompt can be answered.
///
/// Callbacks run on the thread that called [`fetch`], [`push`] or [`remote_head`], one at a time
/// and in the order events occur. The transfer waits while a callback runs, so return promptly;
/// a credential prompt that waits for the user is expected to block. Callbacks cannot cancel the
/// transfer.
///
/// All message bytes come from the remote or a local process and are untrusted. They need not be
/// UTF-8 and may contain terminal control sequences; sanitize them before display.
///
/// # Examples
///
/// Show the remote's progress the way a terminal would, and answer prompts with a token, as a
/// non-interactive client might:
///
/// ```
/// use girt::workflow::{CredentialPrompt, TransferCallbacks};
///
/// #[derive(Default)]
/// struct Display {
///     /// Bytes of the line received so far.
///     pending: Vec<u8>,
///     /// The line currently being redrawn, if any.
///     progress: Option<String>,
///     /// Finished lines.
///     lines: Vec<String>,
///     token: Option<String>,
/// }
///
/// impl TransferCallbacks for Display {
///     fn remote_message(&mut self, message: &[u8]) {
///         // A call can hold several lines or part of one, so buffer bytes until a terminator
///         // before decoding: a split multi-byte character then stays intact.
///         for &byte in message {
///             if byte != b'\r' && byte != b'\n' {
///                 self.pending.push(byte);
///                 continue;
///             }
///             let line = String::from_utf8_lossy(&std::mem::take(&mut self.pending)).into_owned();
///             if byte == b'\r' {
///                 // `\r` asks for the line to be redrawn by the next one.
///                 self.progress = Some(line);
///             } else {
///                 self.progress = None;
///                 self.lines.push(line);
///             }
///         }
///     }
///
///     fn credential(&mut self, _url: &str, prompt: CredentialPrompt) -> Option<Vec<u8>> {
///         match prompt {
///             // Many hosts accept any username alongside a token.
///             CredentialPrompt::Username => Some(b"x-access-token".to_vec()),
///             CredentialPrompt::Password => self.token.clone().map(String::into_bytes),
///             _ => None,
///         }
///     }
/// }
///
/// let mut display = Display {
///     token: Some("secret".into()),
///     ..Display::default()
/// };
///
/// display.remote_message(b"Counting objects:  50% (1/2)\rCounting obj");
/// assert_eq!(
///     display.progress.as_deref(),
///     Some("Counting objects:  50% (1/2)")
/// );
///
/// display.remote_message(b"ects: 100% (2/2), done.\n");
/// assert_eq!(display.lines, ["Counting objects: 100% (2/2), done."]);
/// assert_eq!(display.progress, None);
///
/// assert_eq!(
///     display.credential("https://example.com/repo.git", CredentialPrompt::Password),
///     Some(b"secret".to_vec()),
/// );
/// ```
pub trait TransferCallbacks {
    /// Receives a progress or informational message from the remote, as raw bytes.
    ///
    /// These are the `remote: …` lines `git` prints: object counting and compression progress,
    /// and messages from the server's hooks, such as a link to open a pull request. A message
    /// ending in `\r` is meant to be overwritten by the next one; `\n` ends a line. One call
    /// may carry several lines or part of one, so buffer until a terminator before parsing.
    fn remote_message(&mut self, _message: &[u8]) {}

    /// Receives counts of objects and deltas validated so far, for a local transfer.
    ///
    /// Validation checks every received object before installation, and is the longest local
    /// phase of a large fetch or push. Each call carries a cumulative snapshot; use it to draw a
    /// progress bar. Completion means validation finished, not that objects were installed or
    /// references updated. A transfer with no pack makes no calls, and counts may start over if
    /// a push is prepared again.
    ///
    /// Fetch reports this for native local, HTTP and SSH validation; native local push reports
    /// receiver validation. Remote-owned push validation is reported through
    /// [`Self::remote_message`] instead. A panic unwinds before received data is installed.
    fn validation_progress(&mut self, _progress: crate::fetch::ValidationProgress) {}

    /// Receives synchronous source traversal and pack construction counts for native local fetch.
    /// Completion precedes installation and reference publication.
    fn fetch_progress(&mut self, _progress: crate::fetch::LocalFetchProgress) {}

    /// Receives completed and total working-tree operations during clone checkout.
    /// Completion precedes index publication; inspect the checkout report for final effects.
    fn checkout_progress(&mut self, _done: u64, _total: u64) {}

    /// Receives synchronous source traversal and pack construction counts while preparing a push.
    /// Counts may restart on retry; completion does not imply upload or receiver acceptance.
    fn push_progress(&mut self, _progress: crate::push::PreparationProgress) {}

    /// Receives diagnostic output of a local transport process, as raw bytes.
    ///
    /// For SSH this is the `ssh` client's standard error: host-key warnings, "Permission denied
    /// (publickey)" and similar. Show it to the user when a transfer fails, since it usually
    /// explains why. Chunks are not aligned to lines.
    fn transport_message(&mut self, _message: &[u8]) {}

    /// Asks the user for part of a credential, after configured helpers and the askpass program
    /// (`GIT_ASKPASS`, `core.askPass` or `SSH_ASKPASS`) didn't supply one.
    ///
    /// Called only for HTTP(S) remotes that answer `401 Unauthorized`. `url` identifies the
    /// remote for the prompt; it never contains a username or password. Return the bytes the user
    /// entered, or `None` to cancel, which fails the transfer with
    /// [`TransferError::Authentication`]. A credential the server accepts is passed to the
    /// configured `credential.helper` programs for storage.
    ///
    /// SSH never calls this: OpenSSH prompts through `SSH_ASKPASS` or its agent instead.
    fn credential(&mut self, _url: &str, _prompt: CredentialPrompt) -> Option<Vec<u8>> {
        None
    }

    /// Returns how SSH remotes check the server's host key, overriding the user's OpenSSH
    /// configuration.
    ///
    /// The default, `None`, leaves host-key checking to OpenSSH and the user's `~/.ssh/config`,
    /// as `git` does. See [`HostKeyPolicy`](crate::transport::ssh::HostKeyPolicy).
    #[cfg(all(feature = "ssh", any(target_os = "macos", target_os = "linux")))]
    fn host_key_policy(&self) -> Option<crate::transport::ssh::HostKeyPolicy> {
        None
    }

    /// Returns which `git-remote-<name>` programs transfers may run. See [`RemoteHelpers`].
    ///
    /// The default refuses all of them.
    fn remote_helpers(&self) -> RemoteHelpers {
        RemoteHelpers::Refuse
    }

    /// Returns the application's transport for a URL scheme girt does not handle itself.
    ///
    /// Called with the scheme of a `<scheme>::<address>` or unrecognized `<scheme>://` URL, such
    /// as `b"mem"` for `mem://repo`. The default, `None`, leaves the URL unsupported. The URL must
    /// still be allowed by `protocol.<scheme>.allow`. See
    /// [`Transport`](crate::transport::Transport).
    fn transport(&self, _scheme: &[u8]) -> Option<std::sync::Arc<dyn crate::transport::Transport>> {
        None
    }

    /// Returns the check that decides whether HTTPS server certificates are acceptable.
    ///
    /// Called once per HTTPS transfer, before connecting. The default, `None`, keeps girt's own
    /// verification. See [`CertificateCheck`](crate::transport::http::CertificateCheck).
    #[cfg(feature = "http")]
    fn certificate_check(
        &self,
    ) -> Option<std::sync::Arc<dyn crate::transport::http::CertificateCheck>> {
        None
    }
}

/// Callbacks that discard all messages and decline every credential prompt.
///
/// Use it for background transfers and tests. A remote that requires a password the configured
/// helpers cannot supply fails with [`TransferError::Authentication`].
///
/// # Examples
///
/// ```
/// use girt::workflow::{self, Environment, NoCallbacks};
/// # let (_directory, _, repo, _, _) = include!("doctest/remote.rs");
///
/// let head = workflow::remote_head(&repo, "origin", &Environment::default(), &mut NoCallbacks)?;
/// # let _ = head;
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
#[derive(Clone, Copy, Debug, Default)]
pub struct NoCallbacks;

impl TransferCallbacks for NoCallbacks {}

/// Which references [`fetch`] downloads and how it records them locally.
///
/// Start with [`FetchOptions::new`] and the refspecs to fetch, then opt into pruning, a depth
/// limit, reflog entries or extra tag namespaces. By default the fetch is a plain `git fetch
/// <remote> <refspecs>`: full history, no pruning and no reflog entries.
///
/// # Examples
///
/// Fetch the remote's branches and tags, delete remote-tracking references for branches that no
/// longer exist, and record a reflog entry for each change:
///
/// ```
/// use girt::workflow::FetchOptions;
/// # let person = girt::Signature {
/// #     name: b"A. Writer".to_vec(),
/// #     email: b"writer@example.com".to_vec(),
/// #     seconds: 1_700_000_000,
/// #     offset_minutes: 0,
/// # };
///
/// let options = FetchOptions::new([
///     "+refs/heads/*:refs/remotes/origin/*",
///     "refs/tags/*:refs/tags/*",
///     // Negative refspecs exclude matching sources, as in Git.
///     "^refs/heads/wip/*",
/// ])
/// .with_prune(true)
/// .with_reflog(person, "fetch origin");
/// # let _ = options;
/// ```
#[derive(Clone, Debug)]
pub struct FetchOptions {
    refspecs: Vec<Vec<u8>>,
    depth: Option<NonZeroU32>,
    /// `None` reuses the remote's configured filter; `Some(None)` fetches unfiltered.
    filter: Option<Option<ObjectFilter>>,
    prune: bool,
    auto_pack_refs: bool,
    tag_namespaces: Vec<RefName>,
    reflog: Option<(crate::Signature, Vec<u8>)>,
}

impl FetchOptions {
    /// Fetches with the given refspecs and no other options.
    ///
    /// Each refspec uses Git's syntax: `[+]<src>:<dst>` maps remote references to local ones, `*`
    /// matches one glob segment, a leading `+` permits non-fast-forward updates, and `^<src>`
    /// excludes sources. A refspec with no destination (`refs/heads/main`) downloads the objects
    /// without recording a reference. Refspecs are parsed when the fetch starts; an invalid one
    /// fails it with [`TransferError::Configuration`] before any network access.
    ///
    /// An empty list fetches nothing.
    ///
    /// # Examples
    ///
    /// ```
    /// use girt::workflow::{self, Environment, FetchOptions, NoCallbacks, TransferError};
    /// # let (_directory, _, repo, _, _) = include!("doctest/remote.rs");
    ///
    /// // Two `*` in one side is not a valid refspec, so the fetch fails before connecting.
    /// let options = FetchOptions::new(["refs/heads/*/*:refs/remotes/origin/*"]);
    /// let result = workflow::fetch(
    ///     &repo,
    ///     "origin",
    ///     &options,
    ///     &Environment::default(),
    ///     &mut NoCallbacks,
    /// );
    /// assert!(matches!(result, Err(TransferError::Configuration(_))));
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn new<I, S>(refspecs: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: AsRef<[u8]>,
    {
        Self {
            refspecs: refspecs
                .into_iter()
                .map(|refspec| refspec.as_ref().to_vec())
                .collect(),
            depth: None,
            filter: None,
            prune: false,
            auto_pack_refs: true,
            tag_namespaces: Vec::new(),
            reflog: None,
        }
    }

    /// Enables automatic reference packing after a successful fetch (default: true).
    ///
    /// The default runs [`Repository::auto_pack_references`], honoring its configuration and
    /// threshold; a packing failure never fails the completed fetch. Set this to false when the
    /// caller composes its own bounded maintenance. Newly updated references then stay loose,
    /// while existing packed records remain in place. Transfer and reference updates are unchanged.
    ///
    /// ```
    /// use girt::workflow::FetchOptions;
    ///
    /// let options =
    ///     FetchOptions::new(["+refs/heads/*:refs/remotes/origin/*"]).with_auto_pack_refs(false);
    /// # let _ = options;
    /// ```
    #[must_use]
    pub fn with_auto_pack_refs(mut self, enabled: bool) -> Self {
        self.auto_pack_refs = enabled;
        self
    }

    /// Limits history to `depth` commits from each fetched tip, like `git fetch --depth`.
    ///
    /// The repository becomes shallow: the oldest fetched commits are recorded in
    /// `.git/shallow` as boundaries whose parents are absent. Fetching again with a larger depth
    /// deepens the history, and the boundaries move. `None` (the default) fetches complete
    /// history from a complete repository and keeps existing boundaries in a shallow one.
    ///
    /// Native local remotes support only a depth of one, with a single fetched branch, from a
    /// complete (not shallow) source.
    ///
    /// # Examples
    ///
    /// ```
    /// use std::num::NonZeroU32;
    ///
    /// use girt::workflow::FetchOptions;
    ///
    /// let latest_only = FetchOptions::new(["+refs/heads/main:refs/remotes/origin/main"])
    ///     .with_depth(NonZeroU32::new(1));
    /// # let _ = latest_only;
    /// ```
    #[must_use]
    pub fn with_depth(mut self, depth: Option<NonZeroU32>) -> Self {
        self.depth = depth;
        self
    }

    /// Asks the remote to leave out the objects `filter` matches, like `git fetch --filter`.
    ///
    /// The remote becomes a promisor, as with `git clone --filter`: the fetch writes
    /// `remote.<name>.promisor = true` and `remote.<name>.partialclonefilter = <spec>`, and raises
    /// `core.repositoryformatversion` to 1. Git then fetches omitted objects from that remote on
    /// demand; girt reads never do, and [`fetch_promised`] fetches them explicitly. Without this or
    /// [`Self::without_filter`], a fetch reuses the remote's configured `partialclonefilter`,
    /// if any, so later fetches of a partial clone stay partial.
    ///
    /// A remote that does not support filtering sends every object instead, which
    /// [`FetchOutcome::filter_applied`] reports. girt fetches local remotes, both paths and
    /// `file://` URLs, without upload-pack, so they always send every object.
    ///
    /// # Examples
    ///
    /// ```
    /// use girt::fetch::ObjectFilter;
    /// use girt::workflow::FetchOptions;
    ///
    /// // Commits and trees only; file contents stay on the remote.
    /// let blobless = FetchOptions::new(["+refs/heads/*:refs/remotes/origin/*"])
    ///     .with_filter(ObjectFilter::BlobNone);
    /// # let _ = blobless;
    /// ```
    #[must_use]
    pub fn with_filter(mut self, filter: ObjectFilter) -> Self {
        self.filter = Some(Some(filter));
        self
    }

    /// Fetches every object even when the remote has a configured `partialclonefilter`, like
    /// `git fetch --no-filter`. The promisor configuration is left as it is.
    #[must_use]
    pub fn without_filter(mut self) -> Self {
        self.filter = Some(None);
        self
    }

    /// Deletes local destinations whose remote sources no longer exist, like `git fetch --prune`.
    ///
    /// Pruning applies to remote-tracking references under `refs/remotes/` and to any
    /// [`Self::with_tag_namespace`], within the destinations the refspecs could produce. For a glob
    /// refspec, that is every existing reference the destination pattern matches; for an exact
    /// refspec, its one destination. Ordinary tags under `refs/tags/` are never pruned. Pruned
    /// references lose their reflogs, as in Git.
    ///
    /// # Examples
    ///
    /// ```
    /// use girt::refs::{Expected, RefName};
    /// use girt::workflow::{self, Environment, FetchOptions, NoCallbacks};
    /// # let (_directory, upstream, repo, _, _) = include!("doctest/remote.rs");
    /// let environment = Environment::default();
    /// let options = FetchOptions::new(["+refs/heads/*:refs/remotes/origin/*"]).with_prune(true);
    /// workflow::fetch(&repo, "origin", &options, &environment, &mut NoCallbacks)?;
    ///
    /// // `main` is deleted upstream, so the next fetch deletes its remote-tracking reference.
    /// let main = RefName::new("refs/heads/main")?;
    /// let id = upstream.references()?.read(&main)?.expect("main exists");
    /// upstream
    ///     .references()?
    ///     .delete_without_reflog(&main, Expected::Value(id))?;
    ///
    /// let outcome = workflow::fetch(&repo, "origin", &options, &environment, &mut NoCallbacks)?;
    /// assert_eq!(outcome.updated.len(), 1);
    /// assert_eq!(outcome.updated[0].new, None, "pruned");
    /// assert_eq!(
    ///     repo.references()?
    ///         .read(&RefName::new("refs/remotes/origin/main")?)?,
    ///     None
    /// );
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    #[must_use]
    pub fn with_prune(mut self, prune: bool) -> Self {
        self.prune = prune;
        self
    }

    /// Allows fetching tags into references below `namespace`, such as `refs/remote-tags/origin`.
    ///
    /// By default a fetch writes only remote-tracking references and `refs/tags/`. Keeping each
    /// remote's tags in its own namespace avoids conflicts when two remotes have a tag with the
    /// same name, which is how jj stores remote tags. References in such a namespace behave like
    /// remote-tracking references: a forced refspec may replace them, and [`Self::with_prune`]
    /// deletes them when the remote's tag disappears. Call this once per namespace.
    ///
    /// # Examples
    ///
    /// ```
    /// use girt::refs::RefName;
    /// use girt::workflow::FetchOptions;
    ///
    /// let options = FetchOptions::new(["+refs/tags/*:refs/remote-tags/origin/*"])
    ///     .with_tag_namespace(RefName::new("refs/remote-tags/origin")?)
    ///     .with_prune(true);
    /// # let _ = options;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    #[must_use]
    pub fn with_tag_namespace(mut self, namespace: RefName) -> Self {
        self.tag_namespaces.push(namespace);
        self
    }

    /// Appends a reflog entry by `committer` with `message` for each changed reference Git would
    /// log.
    ///
    /// As with `git fetch`, `core.logAllRefUpdates` decides: by default, remote-tracking
    /// references are logged, while tags and references below a
    /// [tag namespace](Self::with_tag_namespace) are logged only when they already have a log.
    /// `always` logs every changed reference. Without this, no reflog entries are written and
    /// existing reflogs are left alone. `git fetch` uses messages such as `fetch origin`.
    /// Unchanged references get no entry.
    #[must_use]
    pub fn with_reflog(mut self, committer: crate::Signature, message: impl Into<Vec<u8>>) -> Self {
        self.reflog = Some((committer, message.into()));
        self
    }
}

/// One local reference that a [`fetch`] created, moved or deleted.
///
/// `old` and `new` describe the change: `old: None` is a new reference, `new: None` a pruned
/// one, and both set a moved one.
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub struct FetchedRef {
    /// Local reference name.
    pub name: RefName,
    /// Previous value, if the reference existed.
    pub old: Option<ObjectId>,
    /// New value, or `None` if the reference was pruned.
    pub new: Option<ObjectId>,
}

/// What a successful [`fetch`] changed locally.
///
/// # Examples
///
/// Summarize a fetch the way `git fetch` reports it:
///
/// ```
/// use girt::workflow::{self, Environment, FetchOptions, NoCallbacks};
/// # let (_directory, _, repo, _, _) = include!("doctest/remote.rs");
///
/// let options = FetchOptions::new([
///     "+refs/heads/*:refs/remotes/origin/*",
///     "+refs/heads/gone:refs/remotes/origin/gone",
/// ]);
/// let outcome = workflow::fetch(
///     &repo,
///     "origin",
///     &options,
///     &Environment::default(),
///     &mut NoCallbacks,
/// )?;
///
/// for change in &outcome.updated {
///     let name = String::from_utf8_lossy(change.name.as_bytes());
///     match (change.old, change.new) {
///         (None, Some(_)) => println!(" * [new]     {name}"),
///         (Some(_), None) => println!(" - [deleted] {name}"),
///         _ => println!("   [updated] {name}"),
///     }
/// }
///
/// for source in &outcome.missing_sources {
///     println!(
///         "couldn't find remote ref {}",
///         String::from_utf8_lossy(source)
///     );
/// }
///
/// assert_eq!(outcome.missing_sources, [b"refs/heads/gone".to_vec()]);
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct FetchOutcome {
    /// Local references that were created, updated or pruned, in refspec order. References that
    /// already had the fetched value are not listed.
    pub updated: Vec<FetchedRef>,
    /// Sources of exact (non-glob) refspecs that the remote doesn't have, as written in the
    /// refspec. Git fails the whole fetch in this case; girt fetches the rest and reports them
    /// here.
    pub missing_sources: Vec<Vec<u8>>,
    /// The remote applied the requested object filter, so the fetched pack may omit objects.
    /// `false` when no filter was in effect, or when the remote does not support filtering and
    /// sent every object; Git warns "filtering not recognized by server, ignoring" there.
    pub filter_applied: bool,
}

/// Options for [`push`] beyond the commands themselves.
///
/// The default sends no push options, writes no reflog entries in a local destination, and uses
/// girt's bounded delta compression.
///
/// # Examples
///
/// ```
/// use girt::workflow::PushOptions;
/// # let person = girt::Signature {
/// #     name: b"A. Writer".to_vec(),
/// #     email: b"writer@example.com".to_vec(),
/// #     seconds: 1_700_000_000,
/// #     offset_minutes: 0,
/// # };
///
/// // Ask a Gerrit server to add a reviewer, and record who pushed in local reflogs.
/// let options = PushOptions::default()
///     .with_push_option("r=reviewer@example.com")
///     .with_identity(person);
/// # let _ = options;
/// ```
#[derive(Clone, Debug, Default)]
pub struct PushOptions {
    push_options: Vec<Vec<u8>>,
    identity: Option<crate::Signature>,
    compression: Option<crate::PackCompression>,
    hooks: crate::hooks::Policy,
}

impl PushOptions {
    /// Chooses whether the push runs the repository's `pre-push` hook, as `git push` does.
    ///
    /// The default, [`Policy::Ignore`](crate::hooks::Policy::Ignore), runs nothing. With
    /// [`Policy::Run`](crate::hooks::Policy::Run), `pre-push` runs once the receiver's
    /// references are known and before any pack is prepared or sent. Its arguments are the
    /// remote name and its resolved URL (after `url.<base>.insteadOf` and `pushInsteadOf`), and
    /// its standard input holds one `<local> <new> <remote ref> <old>` line per command that
    /// would change the receiver, where `<old>` is the receiver's current value. Commands whose
    /// expected value already differs from the receiver, or that would leave it unchanged, are
    /// left out, as Git leaves out rejected and up-to-date references. Because girt pushes object
    /// IDs rather than local references, `<local>` is the new ID (`(delete)` for a deletion), as
    /// when running `git push origin <id>:<ref>`. A failing hook stops the push before anything
    /// is sent, with [`TransferError::Hook`] holding
    /// [`hooks::Error::Rejected`](crate::hooks::Error::Rejected).
    #[must_use]
    pub fn with_hooks(mut self, policy: crate::hooks::Policy) -> Self {
        self.hooks = policy;
        self
    }

    /// Selects compression for a configured push, replacing the default bounded delta policy.
    ///
    /// Both policies can reuse eligible stored compressed entries and internal deltas. Ordinary
    /// compression disables new internal/external delta search. Delta search respects its bounds;
    /// packs offering advertised receiver candidates additionally cap output depth at one.
    ///
    /// ```
    /// let _options =
    ///     girt::workflow::PushOptions::default().with_compression(girt::PackCompression::Ordinary);
    /// ```
    #[must_use]
    pub fn with_compression(mut self, compression: crate::PackCompression) -> Self {
        self.compression = Some(compression);
        self
    }

    /// Sets the identity for reflog entries this push writes.
    ///
    /// The identity is used for reflog entries in a native local destination, and for the local
    /// remote-tracking references a successful push updates (message `update by push`). Without
    /// it, those references are updated without reflog entries. Network servers write their own
    /// reflogs; this identity is not sent to them.
    #[must_use]
    pub fn with_identity(mut self, identity: crate::Signature) -> Self {
        self.identity = Some(identity);
        self
    }

    /// Adds one server-specific value, like `git push --push-option`.
    ///
    /// Servers use push options for per-push settings such as Gerrit reviewers or GitLab merge
    /// request creation. Values are sent as given, in order. Push options require the server to
    /// advertise `push-options`; otherwise the push fails before any command is sent.
    #[must_use]
    pub fn with_push_option(mut self, option: impl Into<Vec<u8>>) -> Self {
        self.push_options.push(option.into());
        self
    }
}

/// How the remote's `HEAD` is configured, as advertised; an alias of [`RemoteHead`].
pub type RemoteHeadState = RemoteHead;

/// Why [`fetch`], [`push`] or [`remote_head`] failed, and how far it got.
///
/// The variants are ordered by how far the operation progressed. Only
/// [`FetchFinish`](Self::FetchFinish) and an uncertain [`Push`](Self::Push) can follow a change;
/// every other variant means nothing was changed locally or remotely. The
/// [module documentation](self#errors) has a table of recovery actions.
///
/// For SSH failures, also show the text received by [`TransferCallbacks::transport_message`]:
/// OpenSSH explains authentication and host-key problems there.
///
/// # Examples
///
/// ```
/// use girt::workflow::{self, Environment, FetchOptions, NoCallbacks, TransferError};
/// # let (_directory, _, repo, _, _) = include!("doctest/remote.rs");
///
/// let options = FetchOptions::new(["+refs/heads/*:refs/remotes/upstream/*"]);
/// match workflow::fetch(
///     &repo,
///     "upstream",
///     &options,
///     &Environment::default(),
///     &mut NoCallbacks,
/// ) {
///     Err(TransferError::NoSuchRemote(name)) => assert_eq!(name, "upstream"),
///     other => panic!("expected a missing remote, got {other:?}"),
/// }
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum TransferError {
    /// No remote has this name, or it has no URL for this direction.
    ///
    /// Holds the remote name.
    #[error("no such remote: {0}")]
    NoSuchRemote(String),
    /// The remote's configuration or the environment is invalid or unsupported.
    ///
    /// Examples: an unparsable refspec, a URL rewritten to a form girt cannot parse, a protocol
    /// refused by `protocol.allow`, an invalid `protocol.version`, an unreadable `GIT_SSL_CAINFO`
    /// file, or an HTTP setting girt does not implement. Holds a description. Nothing was sent.
    #[error("invalid remote configuration: {0}")]
    Configuration(String),
    /// The URL's transport is not available in this build or not supported at all.
    ///
    /// `http(s)://` URLs need the `http` feature and SSH URLs need the `ssh` feature on macOS or
    /// Linux. Other schemes need an application transport from [`TransferCallbacks::transport`]
    /// or a remote helper approved by [`TransferCallbacks::remote_helpers`]. `git://` is not
    /// supported. Holds the remote name.
    #[error("unsupported transport for remote {0}")]
    UnsupportedTransport(String),
    /// The application's [`Transport`](crate::transport::Transport) could not connect, or its
    /// service failed.
    #[error(transparent)]
    Transport(#[from] crate::transport::ConnectError),
    /// An HTTP server asked for a credential and none could be obtained.
    ///
    /// Raised when credential helpers and [`TransferCallbacks::credential`] supply nothing or the
    /// user cancels the prompt. Holds the remote URL without any username or password. A
    /// credential the server then rejects is reported as an HTTP `401` status through
    /// [`Fetch`](Self::Fetch) or [`Push`](Self::Push). SSH authentication failures are reported
    /// by OpenSSH through those variants as well.
    #[error("authentication failed for {0}")]
    Authentication(String),
    /// The fetch failed before installing anything; the repository is unchanged.
    ///
    /// The boxed error distinguishes a refspec or destination policy problem
    /// ([`FetchWorkflowError::Plan`]) from a transport, protocol or validation failure
    /// ([`FetchWorkflowError::Transfer`]).
    #[error(transparent)]
    Fetch(Box<FetchWorkflowError>),
    /// The fetch validated the pack but failed while installing it or publishing the results.
    ///
    /// The boxed [`FetchFinishError`](crate::fetch::FetchFinishError) holds a report of the
    /// completed phases and the failure. Check `report.installed` before assuming objects were
    /// installed: a failed installation can leave an unindexed pack file behind. After
    /// installation, `.git/shallow` may already have changed (`report.shallow_published`), and a
    /// reference transaction failure carries the references it did publish. Nothing is rolled
    /// back; installed objects that nothing refers to are removed by later maintenance.
    #[error(transparent)]
    FetchFinish(Box<crate::fetch::FetchFinishError>),
    /// The push failed; the boxed [`PushError`](crate::push::PushError) says whether the remote
    /// may have changed.
    #[error(transparent)]
    Push(Box<crate::push::PushError>),
    /// Reading this repository's objects or references failed before the transfer began.
    #[error(transparent)]
    Local(Box<dyn std::error::Error + Send + Sync>),
    /// A hook could not run or rejected the operation before anything was sent.
    #[error(transparent)]
    Hook(Box<crate::hooks::Error>),
    /// The remote is not a promisor, so it never promised the objects a partial clone lacks.
    ///
    /// Holds the remote name. A promisor remote has `remote.<name>.promisor = true` or is named by
    /// `extensions.partialClone`. Nothing was sent.
    #[error("remote {0} is not a promisor remote")]
    NotPromisor(String),
    /// No configured remote is a promisor, so there is nowhere to fetch promised objects from.
    #[error("no promisor remote is configured")]
    NoPromisorRemote,
    /// The remote's pack lacked these requested objects.
    ///
    /// The pack was installed, so the objects it did contain are stored.
    #[error("{} requested objects were not fetched, including {}", .0.len(), .0.first().map(ToString::to_string).unwrap_or_default())]
    NotFetched(Vec<ObjectId>),
}

impl TransferError {
    fn local(error: impl Into<Box<dyn std::error::Error + Send + Sync>>) -> Self {
        Self::Local(error.into())
    }
}

/// A resolved connection target.
enum Endpoint {
    Local(PathBuf),
    Custom(Box<Custom>),
    #[cfg(feature = "http")]
    Http(Box<Http>),
    #[cfg(all(feature = "ssh", any(target_os = "macos", target_os = "linux")))]
    Ssh(Box<crate::transport::ssh::SshRemote>),
}

// A remote reached through an application's transport.
struct Custom {
    transport: std::sync::Arc<dyn crate::transport::Transport>,
    destination: Destination,
    protocol: crate::transport::RequestedProtocol,
}

impl Custom {
    fn connect(
        &self,
        service: crate::transport::Service,
    ) -> Result<std::cell::RefCell<Box<dyn crate::transport::Connection>>, TransferError> {
        let request = crate::transport::ConnectRequest {
            destination: &self.destination,
            service,
            protocol: self.protocol,
        };
        Ok(std::cell::RefCell::new(self.transport.connect(&request)?))
    }
}

// Whether a fetch failed in the exchange itself, which a failed service explains; a local or
// policy failure stays girt's own.
fn is_stream_failure(error: &crate::fetch::FetchError) -> bool {
    matches!(
        error,
        crate::fetch::FetchError::Io(_) | crate::fetch::FetchError::Protocol(_)
    )
}

// The reading and writing halves of one connection, for stream functions that take both.
struct Half<'a>(&'a std::cell::RefCell<Box<dyn crate::transport::Connection>>);

impl std::io::Read for Half<'_> {
    fn read(&mut self, buffer: &mut [u8]) -> std::io::Result<usize> {
        self.0.borrow_mut().read(buffer)
    }
}

impl std::io::Write for Half<'_> {
    fn write(&mut self, buffer: &[u8]) -> std::io::Result<usize> {
        self.0.borrow_mut().write(buffer)
    }

    fn flush(&mut self) -> std::io::Result<()> {
        self.0.borrow_mut().flush()
    }
}

#[cfg(feature = "http")]
struct Http {
    settings_config: crate::Config,
    remote_name: Vec<u8>,
    destination: Destination,
    environment: crate::transport::http::HttpEnvironment,
    protocol: crate::transport::RequestedProtocol,
    helpers: Vec<crate::remote::CredentialHelper>,
    /// `GIT_ASKPASS`, `core.askPass` or `SSH_ASKPASS`, asked before the callbacks.
    askpass: Option<crate::remote::CredentialProgram>,
    /// Credentials for a proxy whose URL names a user.
    proxy_login: Option<ProxyLogin>,
    /// URL for prompts, without userinfo.
    display_url: String,
}

#[cfg(feature = "http")]
struct ProxyLogin {
    credentials: (String, String),
    // The helpers to notify; `None` when the proxy URL held the password.
    session: Option<crate::remote::CredentialSession>,
}

#[cfg(feature = "http")]
impl Http {
    fn remote(
        &self,
        credentials: Option<crate::remote::CredentialSession>,
    ) -> Result<crate::transport::http::HttpRemote, TransferError> {
        let settings = crate::transport::http::HttpSettings::resolve_for_remote(
            &self.settings_config,
            &self.remote_name,
            &self.destination,
            &self.environment,
        )
        .map_err(|error| TransferError::Configuration(error.to_string()))?;
        let settings = match &self.proxy_login {
            Some(login) => settings.with_proxy_credentials(Some(login.credentials.clone())),
            None => settings,
        };
        let remote = crate::transport::http::HttpRemote::configured(settings)
            .map_err(|error| TransferError::Configuration(error.to_string()))?
            .with_protocol(self.protocol);
        match credentials {
            Some(session) => remote
                .with_credentials(session)
                .map_err(|error| TransferError::Configuration(error.to_string())),
            None => Ok(remote),
        }
    }

    // Like Git, a proxy URL that names a user asks the credential helpers, then askpass, for its
    // password before the first request. The application's own prompt is not asked for proxies.
    fn proxy_login(&self) -> Result<Option<ProxyLogin>, TransferError> {
        let settings = crate::transport::http::HttpSettings::resolve_for_remote(
            &self.settings_config,
            &self.remote_name,
            &self.destination,
            &self.environment,
        )
        .map_err(|error| TransferError::Configuration(error.to_string()))?;
        let Some(context) = settings.proxy_credential_context() else {
            return Ok(None);
        };
        let username =
            String::from_utf8_lossy(context.username.as_deref().unwrap_or_default()).into_owned();
        if let Some(password) = settings.proxy_password() {
            return Ok(Some(ProxyLogin {
                credentials: (username, password.to_owned()),
                session: None,
            }));
        }
        let cancel = AtomicBool::new(false);
        let mut prompt = |request: &crate::remote::PromptRequest<'_>| {
            let program = self.askpass.as_ref()?;
            crate::remote::askpass(program, &request.question(), &cancel, None)
                .ok()
                .map(Option::unwrap_or_default)
        };
        let refused = || TransferError::Authentication("HTTP proxy".to_owned());
        let session = crate::remote::CredentialSession::fill_prompting(
            &self.settings_config,
            context,
            &self.helpers,
            Some(&mut prompt),
            &AtomicBool::new(false),
            None,
        )
        .map_err(|_| refused())?;
        let credential = session.credential();
        let password = credential.password.as_deref().ok_or_else(refused)?;
        // Basic proxy credentials are text; changing a helper's bytes would send the wrong ones.
        let text = |bytes: &[u8]| String::from_utf8(bytes.to_vec()).map_err(|_| refused());
        let credentials = (
            text(credential.username.as_deref().unwrap_or_default())?,
            text(password)?,
        );
        Ok(Some(ProxyLogin {
            credentials,
            session: Some(session),
        }))
    }

    // Stores accepted proxy credentials with the helpers that supplied them, as Git does. The
    // proxy accepted them when the server answered, even with 401. Git does not erase them after
    // a 407, and neither does girt; other failures say nothing about the proxy.
    fn settle_proxy(&self, outcome: Result<(), Option<u16>>) {
        let Some(session) = self
            .proxy_login
            .as_ref()
            .and_then(|login| login.session.as_ref())
        else {
            return;
        };
        if matches!(outcome, Ok(()) | Err(Some(401))) {
            let _ = session.approve(&AtomicBool::new(false), None);
        }
    }

    fn credentials(
        &self,
        callbacks: &mut dyn TransferCallbacks,
    ) -> Result<crate::remote::CredentialSession, TransferError> {
        let url = url_parts(self.destination.bytes())
            .ok_or_else(|| TransferError::Configuration("invalid HTTP URL".into()))?;
        let context = crate::remote::CredentialContext {
            protocol: url.scheme.into_bytes(),
            host: url.authority.into_bytes(),
            path: Some(url.path.trim_matches('/').as_bytes().to_vec()),
            use_http_path: false,
            username: None,
        };
        let display_url = self.display_url.clone();
        let cancel = AtomicBool::new(false);
        let mut prompt = |request: &crate::remote::PromptRequest<'_>| {
            // Like Git, an askpass program answers first, and an empty answer is an empty value.
            // A program that fails leaves the question to the application's own prompt.
            if let Some(program) = &self.askpass
                && let Ok(answer) =
                    crate::remote::askpass(program, &request.question(), &cancel, None)
            {
                return Some(answer.unwrap_or_default());
            }
            let prompt = match request.field() {
                crate::remote::Prompt::Password => CredentialPrompt::Password,
                _ => CredentialPrompt::Username,
            };
            callbacks.credential(&display_url, prompt)
        };
        crate::remote::CredentialSession::fill_prompting(
            &self.settings_config,
            context,
            &self.helpers,
            Some(&mut prompt),
            &AtomicBool::new(false),
            None,
        )
        .map_err(|_| TransferError::Authentication(self.display_url.clone()))
    }
}

#[cfg(feature = "http")]
struct UrlParts {
    scheme: String,
    authority: String,
    path: String,
}

/// Splits `scheme://[user@]host[:port]/path` without percent decoding.
#[cfg(feature = "http")]
fn url_parts(bytes: &[u8]) -> Option<UrlParts> {
    let text = std::str::from_utf8(bytes).ok()?;
    let (scheme, rest) = text.split_once("://")?;
    let (authority, path) = rest.split_at(rest.find('/').unwrap_or(rest.len()));
    let authority = authority
        .rsplit_once('@')
        .map_or(authority, |(_, host)| host);
    Some(UrlParts {
        scheme: scheme.to_ascii_lowercase(),
        authority: authority.to_owned(),
        path: path.to_owned(),
    })
}

#[cfg(feature = "http")]
fn redacted_url(bytes: &[u8]) -> String {
    let text = String::from_utf8_lossy(bytes);
    match url_parts(bytes) {
        Some(parts) => format!("{}://{}{}", parts.scheme, parts.authority, parts.path),
        None => text.into_owned(),
    }
}

/// Quotes `value` for a POSIX shell.
#[cfg(any(
    feature = "http",
    all(feature = "ssh", any(target_os = "macos", target_os = "linux"))
))]
fn shell_quote(value: &str) -> String {
    format!("'{}'", value.replace('\'', "'\\''"))
}

/// Finds `program` in the environment's `PATH`.
fn find_program(environment: &Environment, program: &str) -> Option<PathBuf> {
    let path = environment.get("PATH")?;
    std::env::split_paths(path)
        .map(|dir| dir.join(program))
        .find(|candidate| candidate.is_file())
}

/// Whether workflow transfers may run `git-remote-<name>` programs for `<name>::<address>` and
/// unrecognized `<name>://` URLs.
///
/// A remote helper is a program named by the URL, found on `PATH` or in `GIT_EXEC_PATH`, that runs
/// with the permissions of the current process. Git runs any helper a URL names. girt refuses by
/// default and runs only helpers whose names the application approved, such as
/// `RemoteHelpers::Run(vec!["mem".into()])` for `mem://` URLs. The URL must also be allowed by
/// `protocol.<name>.allow`, as Git requires; `ext::` URLs therefore also need
/// `protocol.ext.allow`.
///
/// girt speaks the `connect` part of the remote-helper protocol: it asks for `capabilities`, then
/// `connect git-upload-pack` or `connect git-receive-pack`, and speaks the Git protocol over the
/// helper's standard input and output. Helpers that offer only `fetch`, `push`, `import` or
/// `export`, such as Mercurial bridges, fail with [`TransferError::Transport`]. An application
/// [`Transport`](crate::transport::Transport) for the same scheme takes precedence.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub enum RemoteHelpers {
    /// Run no remote helpers; their URLs are [`TransferError::UnsupportedTransport`].
    #[default]
    Refuse,
    /// Run `git-remote-<name>` only for these names.
    Run(Vec<String>),
}

// An approved remote helper for `scheme`, or `None` when the policy does not allow it.
fn remote_helper(
    policy: &RemoteHelpers,
    scheme: &[u8],
    remote_name: &str,
    git_dir: Option<&Path>,
    environment: &Environment,
) -> Result<Option<std::sync::Arc<dyn crate::transport::Transport>>, TransferError> {
    let RemoteHelpers::Run(names) = policy else {
        return Ok(None);
    };
    let Some(name) = std::str::from_utf8(scheme)
        .ok()
        .filter(|name| names.iter().any(|approved| approved == name))
    else {
        return Ok(None);
    };
    let program = format!("git-remote-{name}");
    let path = find_program(environment, &program)
        .or_else(|| {
            let exec = environment.get("GIT_EXEC_PATH")?;
            Some(Path::new(exec).join(&program)).filter(|path| path.is_file())
        })
        .ok_or_else(|| {
            TransferError::Configuration(format!("remote helper {program} not found"))
        })?;
    let mut variables: Vec<_> = environment
        .vars
        .iter()
        .filter(|(name, _)| name.as_os_str() != "GIT_DIR")
        .map(|(name, value)| (name.clone(), value.clone()))
        .collect();
    if let Some(git_dir) = git_dir {
        variables.push(("GIT_DIR".into(), git_dir.as_os_str().to_owned()));
    }
    Ok(Some(std::sync::Arc::new(
        crate::transport::helper::RemoteHelper {
            program: path,
            remote: remote_name.to_owned(),
            environment: variables,
        },
    )))
}

/// Maps configured `credential.helper` values to helpers, following Git's rules: `!cmd` is a
/// shell snippet, an absolute path is a shell command, and anything else names
/// `git-credential-<name>` (with any arguments). `store`, optionally with `--file`, runs natively.
#[cfg(feature = "http")]
fn credential_helpers(
    config: &crate::Config,
    environment: &Environment,
) -> Vec<crate::remote::CredentialHelper> {
    let exec_dirs: Vec<PathBuf> = environment
        .get("GIT_EXEC_PATH")
        .map(PathBuf::from)
        .into_iter()
        .chain(
            [
                "/opt/homebrew/opt/git/libexec/git-core",
                "/usr/local/opt/git/libexec/git-core",
                "/usr/lib/git-core",
                "/usr/libexec/git-core",
                "/Library/Developer/CommandLineTools/usr/libexec/git-core",
                "/Applications/Xcode.app/Contents/Developer/usr/libexec/git-core",
            ]
            .map(PathBuf::from),
        )
        .collect();
    config
        .entries()
        .iter()
        .filter(|entry| {
            entry.section.eq_ignore_ascii_case(b"credential")
                && entry.name.eq_ignore_ascii_case(b"helper")
        })
        .filter_map(|entry| entry.value.as_deref())
        .filter(|value| !value.is_empty())
        .filter_map(|value| {
            let text = std::str::from_utf8(value).ok()?;
            if let Some(store) = native_store(text, environment) {
                return Some(crate::remote::CredentialHelper {
                    configured_name: value.to_vec(),
                    backend: crate::remote::CredentialBackend::Store(store),
                });
            }
            let command = if let Some(snippet) = text.strip_prefix('!') {
                snippet.to_owned()
            } else if Path::new(text.split_whitespace().next()?).is_absolute() {
                text.to_owned()
            } else {
                let (name, arguments) = text.split_once(' ').unwrap_or((text, ""));
                let program = format!("git-credential-{name}");
                let path = find_program(environment, &program).or_else(|| {
                    exec_dirs
                        .iter()
                        .map(|dir| dir.join(&program))
                        .find(|candidate| candidate.is_file())
                })?;
                format!("{} {arguments}", shell_quote(&path.to_string_lossy()))
            };
            Some(crate::remote::CredentialHelper {
                configured_name: value.to_vec(),
                backend: crate::remote::CredentialBackend::Program(
                    crate::remote::CredentialProgram {
                        executable: PathBuf::from("/bin/sh"),
                        arguments: vec![
                            "-c".into(),
                            format!("{command} \"$@\"").into(),
                            command.into(),
                        ],
                        inherit_environment: false,
                        environment: environment
                            .vars
                            .iter()
                            .map(|(name, value)| (name.clone(), value.clone()))
                            .collect(),
                    },
                ),
            })
        })
        .collect()
}

/// Selects the askpass program as Git does: `GIT_ASKPASS`, then `core.askPass`, then
/// `SSH_ASKPASS`. An empty `GIT_ASKPASS` or `core.askPass` turns askpass off; the program is run
/// directly with the question as its only argument, not through a shell.
#[cfg(feature = "http")]
fn askpass_program(
    config: &crate::Config,
    environment: &Environment,
) -> Option<crate::remote::CredentialProgram> {
    let configured = || {
        config
            .entries()
            .iter()
            .rev()
            .find(|entry| {
                entry.section.eq_ignore_ascii_case(b"core")
                    && entry.subsection.is_none()
                    && entry.name.eq_ignore_ascii_case(b"askpass")
            })
            .map(|entry| {
                OsString::from(
                    String::from_utf8_lossy(entry.value.as_deref().unwrap_or_default())
                        .into_owned(),
                )
            })
    };
    let program = match environment.get("GIT_ASKPASS") {
        Some(program) => program.to_owned(),
        None => configured().or_else(|| environment.get("SSH_ASKPASS").map(ToOwned::to_owned))?,
    };
    if program.is_empty() {
        return None;
    }
    let mut program = crate::remote::CredentialProgram::new(PathBuf::from(program));
    program.environment = environment
        .vars
        .iter()
        .map(|(name, value)| (name.clone(), value.clone()))
        .collect();
    Some(program)
}

/// Recognizes `store`, `store --file <path>` and `store --file=<path>`, which girt answers itself.
/// Other arguments, and paths containing shell syntax, keep using Git's program.
#[cfg(feature = "http")]
fn native_store(text: &str, environment: &Environment) -> Option<crate::remote::CredentialStore> {
    let mut words = text.split_whitespace();
    if words.next()? != "store" {
        return None;
    }
    let home = environment.get("HOME").map(PathBuf::from);
    let file = match (words.next(), words.next()) {
        (None, _) => None,
        (Some("--file"), Some(path)) => Some(path),
        (Some(option), None) => Some(option.strip_prefix("--file=")?),
        _ => return None,
    };
    if words.next().is_some() {
        return None;
    }
    let Some(file) = file else {
        let xdg = environment.get("XDG_CONFIG_HOME").map(PathBuf::from);
        return Some(crate::remote::CredentialStore::user_files(
            home.as_deref(),
            xdg.as_deref(),
        ));
    };
    // Anything the shell would interpret (quotes, expansions, redirections, separators) keeps
    // Git's program, so only plain path bytes are taken literally.
    let plain = |byte: u8| byte.is_ascii_alphanumeric() || b"/._-+,:@%=~".contains(&byte);
    if !file.bytes().all(plain) {
        return None;
    }
    let path = match file.strip_prefix("~/") {
        Some(rest) => home?.join(rest),
        None if file.starts_with('~') => return None,
        None => PathBuf::from(file),
    };
    let path = match &environment.current_dir {
        Some(directory) if path.is_relative() => directory.join(path),
        _ => path,
    };
    Some(crate::remote::CredentialStore::file(path))
}

#[cfg(feature = "http")]
fn http_environment(
    config: &crate::Config,
    destination: &Destination,
    environment: &Environment,
) -> Result<crate::transport::http::HttpEnvironment, TransferError> {
    let paths = crate::transport::http::HttpSettings::configured_tls_paths(config, destination)
        .map_err(|error| TransferError::Configuration(error.to_string()))?;
    // The environment variable wins over the setting. Only a setting that is used is checked,
    // and it expands `~/` like Git paths.
    let select = |variable: &str, configured: Option<&[u8]>| match environment.get(variable) {
        Some(path) => Ok(Some(PathBuf::from(path))),
        None => configured
            .map(|path| {
                if path.is_empty() || path.contains(&0) {
                    return Err(TransferError::Configuration(format!(
                        "empty or invalid path for {variable}'s setting"
                    )));
                }
                let path = String::from_utf8_lossy(path).into_owned();
                Ok(match (path.strip_prefix("~/"), environment.get("HOME")) {
                    (Some(rest), Some(home)) => Path::new(home).join(rest),
                    _ => PathBuf::from(path),
                })
            })
            .transpose(),
    };
    let ssl_ca_info = select("GIT_SSL_CAINFO", paths.ca_info)?
        .map(|path| read_bounded(&path))
        .transpose()?;
    let ssl_cert = select("GIT_SSL_CERT", paths.certificate)?
        .map(|path| read_bounded(&path))
        .transpose()?;
    let ssl_key = select("GIT_SSL_KEY", paths.key)?
        .map(|path| read_bounded(&path))
        .transpose()?;
    let proxy_var = |names: &[&str]| names.iter().find_map(|name| environment.string(name));
    Ok(crate::transport::http::HttpEnvironment {
        ssl_ca_info,
        ssl_cert,
        ssl_key,
        ssl_no_verify: environment
            .bytes("GIT_SSL_NO_VERIFY")
            .map(|value| crate::config::boolean(Some(&value)).unwrap_or(true)),
        proxy: proxy_var(&[
            "https_proxy",
            "HTTPS_PROXY",
            "http_proxy",
            "all_proxy",
            "ALL_PROXY",
        ]),
        no_proxy: proxy_var(&["no_proxy", "NO_PROXY"]),
        proxy_credentials: None,
        allow_insecure_tls: true,
        user_agent: environment.string("GIT_HTTP_USER_AGENT"),
        certificate_check: None,
    })
}

// TLS inputs are limited to 1 MiB; reading one byte more detects a larger file without
// loading it.
#[cfg(feature = "http")]
fn read_bounded(path: &Path) -> Result<Vec<u8>, TransferError> {
    use std::io::Read;
    const LIMIT: u64 = 1024 * 1024;
    let failure = |error: std::io::Error| {
        TransferError::Configuration(format!("reading {}: {error}", path.display()))
    };
    let mut bytes = Vec::new();
    std::fs::File::open(path)
        .map_err(failure)?
        .take(LIMIT + 1)
        .read_to_end(&mut bytes)
        .map_err(failure)?;
    if bytes.len() as u64 > LIMIT {
        return Err(TransferError::Configuration(format!(
            "{} is larger than 1 MiB",
            path.display()
        )));
    }
    Ok(bytes)
}

/// Reads `protocol.version` for an HTTP, SSH or application endpoint, defaulting to v2 like Git.
/// Only upload-pack sends the request; a server answering v0/v1 is accepted. Native local transfer
/// never reads it, so enabling a network feature cannot change local fetch or push.
fn requested_protocol(
    config: &crate::Config,
) -> Result<crate::transport::RequestedProtocol, TransferError> {
    match config.value("protocol", None, "version") {
        None => Ok(crate::transport::RequestedProtocol::V2),
        Some(value) => value
            .and_then(crate::transport::RequestedProtocol::from_config)
            .ok_or_else(|| TransferError::Configuration("invalid protocol.version".into())),
    }
}

#[cfg(all(feature = "ssh", any(target_os = "macos", target_os = "linux")))]
fn ssh_endpoint(
    config: &crate::Config,
    destination: &Destination,
    environment: &Environment,
) -> Result<crate::transport::ssh::SshRemote, TransferError> {
    use crate::transport::ssh::{ApprovedSshCommand, OpenSshOptions, SshRemote};
    // Git runs a configured command through the shell with the SSH arguments appended.
    let configured = environment
        .bytes("GIT_SSH_COMMAND")
        .or_else(|| {
            config
                .string("core", None, "sshcommand")
                .map(<[u8]>::to_vec)
        })
        .map(|command| (command.clone(), command))
        .or_else(|| {
            environment.bytes("GIT_SSH").map(|program| {
                let quoted = shell_quote(&String::from_utf8_lossy(&program));
                (program, quoted.into_bytes())
            })
        });
    let approved_command = configured.map(|(configured, command)| {
        let command = String::from_utf8_lossy(&command).into_owned();
        ApprovedSshCommand {
            configured,
            executable: PathBuf::from("/bin/sh"),
            arguments: vec![
                "-c".into(),
                format!("{command} \"$@\"").into(),
                command.into(),
            ],
        }
    });
    let default_executable =
        find_program(environment, "ssh").unwrap_or_else(|| PathBuf::from("/usr/bin/ssh"));
    // GIT_SSH_VARIANT and ssh.variant only matter for non-OpenSSH clients.
    let environment = environment
        .clone()
        .without("GIT_PROTOCOL")
        .without("GIT_SSH_VARIANT");
    SshRemote::openssh(
        config,
        destination,
        OpenSshOptions {
            default_executable,
            approved_command,
            environment: environment.vars,
        },
    )
    .map_err(|error| TransferError::Configuration(error.to_string()))
}

// Where a transfer runs locally: relative local URLs resolve against `base`, and remote helpers
// get `git_dir` as `GIT_DIR`.
#[derive(Clone, Copy)]
struct LocalPaths<'a> {
    base: &'a Path,
    git_dir: Option<&'a Path>,
}

fn configured_endpoint(
    config: &crate::Config,
    remote: &Remote,
    remote_name: &str,
    direction: Direction,
    paths: LocalPaths<'_>,
    environment: &Environment,
    callbacks: &dyn TransferCallbacks,
) -> Result<(Endpoint, Destination), TransferError> {
    let LocalPaths { base, git_dir } = paths;
    let protocol_environment =
        ProtocolEnvironment::from_environment(|name| environment.bytes(name))
            .map_err(|error| TransferError::Configuration(error.to_string()))?;
    let destination = match direction {
        Direction::Fetch => remote.fetch_destination(config, &protocol_environment),
        Direction::Push => remote
            .push_destinations(config, &protocol_environment)
            .and_then(|destinations| {
                destinations
                    .into_iter()
                    .next()
                    .ok_or(crate::remote::EndpointError::Missing)
            }),
    }
    .map_err(|error| match error {
        crate::remote::EndpointError::Missing => {
            TransferError::NoSuchRemote(remote_name.to_owned())
        }
        error => TransferError::Configuration(error.to_string()),
    })?;
    let endpoint = match destination.protocol() {
        Protocol::Local | Protocol::File => {
            let path = destination
                .local_path()
                .map_err(|error| TransferError::Configuration(error.to_string()))?;
            // Like Git, relative paths are relative to the working directory, falling back to
            // the working tree (or Git directory).
            let base = environment.current_dir.as_deref().unwrap_or(base);
            Endpoint::Local(base.join(path))
        }
        #[cfg(feature = "http")]
        Protocol::Http | Protocol::Https => {
            let mut http = Http {
                environment: http_environment(config, &destination, environment)?
                    .with_certificate_check(callbacks.certificate_check()),
                protocol: requested_protocol(config)?,
                helpers: credential_helpers(config, environment),
                askpass: askpass_program(config, environment),
                display_url: redacted_url(destination.bytes()),
                settings_config: config.clone(),
                remote_name: remote_name.as_bytes().to_vec(),
                destination: destination.clone(),
                proxy_login: None,
            };
            http.proxy_login = http.proxy_login()?;
            Endpoint::Http(Box::new(http))
        }
        #[cfg(all(feature = "ssh", any(target_os = "macos", target_os = "linux")))]
        Protocol::Ssh => {
            let mut ssh = ssh_endpoint(config, &destination, environment)?
                .with_protocol(requested_protocol(config)?);
            if let Some(policy) = callbacks.host_key_policy() {
                ssh = ssh
                    .with_host_keys(&policy)
                    .map_err(|error| TransferError::Configuration(error.to_string()))?;
            }
            Endpoint::Ssh(Box::new(ssh))
        }
        Protocol::Helper => {
            let scheme = destination.helper_scheme().unwrap_or_default();
            let transport = match callbacks.transport(scheme) {
                Some(transport) => transport,
                None => remote_helper(
                    &callbacks.remote_helpers(),
                    scheme,
                    remote_name,
                    git_dir,
                    environment,
                )?
                .ok_or_else(|| TransferError::UnsupportedTransport(remote_name.to_owned()))?,
            };
            Endpoint::Custom(Box::new(Custom {
                transport,
                destination: destination.clone(),
                protocol: requested_protocol(config)?,
            }))
        }
        _ => return Err(TransferError::UnsupportedTransport(remote_name.to_owned())),
    };
    Ok((endpoint, destination))
}

impl Repository {
    fn endpoint(
        &self,
        remote_name: &str,
        direction: Direction,
        environment: &Environment,
        callbacks: &dyn TransferCallbacks,
    ) -> Result<(Endpoint, Destination), TransferError> {
        let config = self.config();
        let remote = Remote::find(config, remote_name.as_bytes())
            .map_err(|error| TransferError::Configuration(error.to_string()))?
            .ok_or_else(|| TransferError::NoSuchRemote(remote_name.to_owned()))?;
        configured_endpoint(
            config,
            &remote,
            remote_name,
            direction,
            LocalPaths {
                base: self.worktree().unwrap_or(self.git_dir()),
                git_dir: Some(self.git_dir()),
            },
            environment,
            callbacks,
        )
    }

    fn remote_head(
        &self,
        remote_name: &str,
        environment: &Environment,
        callbacks: &mut dyn TransferCallbacks,
    ) -> Result<RemoteHead, TransferError> {
        self.discover_remote(remote_name, environment, callbacks)
            .map(|discovery| discovery.head)
    }

    fn discover_remote(
        &self,
        remote_name: &str,
        environment: &Environment,
        callbacks: &mut dyn TransferCallbacks,
    ) -> Result<crate::fetch::RemoteDiscovery, TransferError> {
        let (endpoint, _) =
            self.endpoint(remote_name, Direction::Fetch, environment, &*callbacks)?;
        let cancel = AtomicBool::new(false);
        let control = TransportControl::new(&cancel);
        let limits = FetchLimits::trusted();
        let discovery = match endpoint {
            Endpoint::Local(path) => crate::fetch::discover_local(path, limits, control),
            Endpoint::Custom(custom) => {
                let connection = custom.connect(crate::transport::Service::UploadPack)?;
                let discovery = crate::fetch::discover_session(
                    &mut Half(&connection),
                    &mut Half(&connection),
                    limits,
                    &cancel,
                );
                // Like closing an SSH session after listing: a service that fails after a complete
                // listing says nothing about it, but its failure explains a broken one.
                let finished = connection.into_inner().finish();
                match (discovery, finished) {
                    (Err(_), Err(error)) => return Err(error.into()),
                    (discovery, _) => discovery,
                }
            }
            #[cfg(feature = "http")]
            Endpoint::Http(http) => {
                let runtime = runtime()?;
                let result = runtime.block_on(crate::fetch::discover_http(
                    &http.remote(None)?,
                    limits,
                    control,
                ));
                http.settle_proxy(fetch_status(&result));
                if is_unauthorized_fetch(&result) {
                    let session = http.credentials(callbacks)?;
                    runtime.block_on(crate::fetch::discover_http(
                        &http.remote(Some(session))?,
                        limits,
                        control,
                    ))
                } else {
                    result
                }
            }
            #[cfg(all(feature = "ssh", any(target_os = "macos", target_os = "linux")))]
            Endpoint::Ssh(ssh) => {
                runtime()?.block_on(crate::fetch::discover_ssh(&ssh, limits, control))
            }
        };
        let _ = &callbacks;
        discovery
            .map_err(|error| TransferError::Fetch(Box::new(FetchWorkflowError::Transfer(error))))
    }

    fn fetch(
        &self,
        remote_name: &str,
        options: &FetchOptions,
        environment: &Environment,
        callbacks: &mut dyn TransferCallbacks,
    ) -> Result<FetchOutcome, TransferError> {
        let (endpoint, _) =
            self.endpoint(remote_name, Direction::Fetch, environment, &*callbacks)?;
        let objects = self
            .objects_with(crate::PackLimits::trusted())
            .map_err(TransferError::local)?;
        // One listing supplies the have tips, force authorization and the snapshot every
        // reference edit is conditional on.
        let listed = self
            .references()
            .map_err(TransferError::local)?
            .list()
            .map_err(TransferError::local)?;
        let tips: Vec<ObjectId> = listed
            .iter()
            .filter_map(|reference| match reference.target {
                crate::refs::Target::Direct(id) => Some(id),
                crate::refs::Target::Symbolic(_) => None,
            })
            .collect::<BTreeSet<_>>()
            .into_iter()
            .collect();
        let cancel = AtomicBool::new(false);
        let limits = FetchLimits::trusted();
        let known = if matches!(endpoint, Endpoint::Local(_)) {
            // Keep explicit reference roots as boundary evidence without a wire have-batch walk.
            KnownHistory::from_store_roots(objects, &tips, &cancel).map_err(|error| {
                TransferError::Fetch(Box::new(FetchWorkflowError::Transfer(error)))
            })?
        } else {
            KnownHistory::from_store(objects, &tips, limits, &cancel).map_err(|error| {
                TransferError::Fetch(Box::new(FetchWorkflowError::Transfer(error)))
            })?
        };
        let filter = match &options.filter {
            Some(filter) => filter.clone(),
            None => configured_filter(self.config(), remote_name)?,
        };
        if let Some(filter) = &filter
            && !matches!(endpoint, Endpoint::Local(_))
        {
            crate::fetch::register_promisor(self, remote_name, filter)
                .map_err(TransferError::local)?;
        }
        let request = || {
            let request = self.fetch_request(options, listed.clone())?;
            Ok::<_, TransferError>(match &filter {
                Some(filter) => request.with_filter(filter.clone()),
                None => request,
            })
        };
        let control = TransportControl::new(&cancel);
        #[cfg(feature = "http")]
        let mut on_message = |message: &[u8]| {
            callbacks.remote_message(message);
            ControlFlow::Continue(())
        };
        let ready = match endpoint {
            Endpoint::Custom(custom) => {
                let mut connection = custom.connect(crate::transport::Service::UploadPack)?;
                let download = request()?.receive_connection(
                    &mut **connection.get_mut(),
                    custom.protocol,
                    Some(std::sync::Arc::new(known)),
                    limits,
                    &cancel,
                    |message| callbacks.remote_message(message),
                );
                // A service that fails after a good response says nothing about it, but its failure
                // explains a broken or invalid one.
                let finished = connection.into_inner().finish();
                let validated = download.and_then(|download| {
                    download.validate_with_progress(
                        &cancel,
                        |_| ControlFlow::Continue(()),
                        |event| callbacks.validation_progress(event),
                    )
                });
                if let (Err(FetchWorkflowError::Transfer(cause)), Err(error)) =
                    (&validated, finished)
                    && is_stream_failure(cause)
                {
                    return Err(error.into());
                }
                validated
            }
            Endpoint::Local(path) => {
                let callbacks = std::cell::RefCell::new(callbacks);
                request()?.receive_local(
                    path,
                    &known,
                    limits,
                    control,
                    crate::fetch::LocalFetchObserver::default()
                        .with_messages(&mut |message| {
                            callbacks.borrow_mut().remote_message(message);
                            ControlFlow::Continue(())
                        })
                        .with_construction(&mut |event| {
                            callbacks.borrow_mut().fetch_progress(event)
                        })
                        .with_validation(&mut |event| {
                            callbacks.borrow_mut().validation_progress(event)
                        }),
                )
            }
            #[cfg(feature = "http")]
            Endpoint::Http(http) => {
                let runtime = runtime()?;
                let known = std::sync::Arc::new(known);
                let receive = |remote: crate::transport::http::HttpRemote,
                               messages: &mut dyn FnMut(&[u8]) -> ControlFlow<()>|
                 -> Result<_, TransferError> {
                    let download = runtime.block_on(request()?.receive_http_with_progress(
                        &remote,
                        Some(known.clone()),
                        limits,
                        control,
                        |message| {
                            let _ = messages(message);
                        },
                    ));
                    Ok(download)
                };
                let mut download = receive(http.remote(None)?, &mut on_message)?;
                http.settle_proxy(match &download {
                    Ok(_) => Ok(()),
                    Err(FetchWorkflowError::Transfer(error)) => Err(status_of(error)),
                    Err(_) => Err(None),
                });
                if matches!(
                    &download,
                    Err(FetchWorkflowError::Transfer(
                        crate::fetch::FetchError::Http(crate::transport::http::HttpError::Status(
                            401
                        ))
                    ))
                ) {
                    let session = http.credentials(callbacks)?;
                    download = receive(http.remote(Some(session))?, &mut |message| {
                        callbacks.remote_message(message);
                        ControlFlow::Continue(())
                    })?;
                }
                download.and_then(|download| {
                    download.validate_with_progress(
                        &cancel,
                        |_| ControlFlow::Continue(()),
                        |event| callbacks.validation_progress(event),
                    )
                })
            }
            #[cfg(all(feature = "ssh", any(target_os = "macos", target_os = "linux")))]
            Endpoint::Ssh(ssh) => {
                let callbacks = std::cell::RefCell::new(&mut *callbacks);
                let download = runtime()?.block_on(request()?.receive_ssh_with_progress(
                    &ssh,
                    Some(std::sync::Arc::new(known)),
                    limits,
                    control,
                    |message| callbacks.borrow_mut().transport_message(message),
                    |message| callbacks.borrow_mut().remote_message(message),
                ));
                download.and_then(|download| {
                    download.validate_with_progress(
                        &cancel,
                        |_| ControlFlow::Continue(()),
                        |event| callbacks.borrow_mut().validation_progress(event),
                    )
                })
            }
        }
        .map_err(|error| TransferError::Fetch(Box::new(error)))?;
        let filter_applied = ready.received().filter_applied();
        let report = ready
            .finish(FetchUpdateLimits::trusted(), &cancel)
            .map_err(|error| TransferError::FetchFinish(Box::new(error)))?;
        if options.auto_pack_refs {
            // Like the automatic maintenance `git fetch` runs afterwards, packing never fails the
            // fetch: its references are already updated, and a held lock means another process is
            // maintaining them. A fresh snapshot includes the received pack, needed to peel new
            // tags.
            #[cfg(test)]
            pack_tests::BEFORE_AUTO_PACK.with(|hook| hook.take().map(|hook| hook()));
            if let Ok(objects) = self.objects_with(crate::PackLimits::trusted()) {
                let _ = self.auto_pack_references(&objects);
            }
        }
        Ok(FetchOutcome {
            updated: report
                .updates
                .iter()
                .filter(|update| {
                    !matches!(
                        update.kind,
                        FetchUpdateKind::SourceOnly | FetchUpdateKind::Unchanged
                    )
                })
                .filter_map(|update| {
                    Some(FetchedRef {
                        name: update.mapping.destination.clone()?,
                        old: update.previous,
                        new: update.mapping.source.as_ref().map(|source| source.id),
                    })
                })
                .collect(),
            missing_sources: report.missing,
            filter_applied,
        })
    }

    fn fetch_request(
        &self,
        options: &FetchOptions,
        listed: Vec<crate::refs::Reference>,
    ) -> Result<FetchRequest, TransferError> {
        let specs = Refspecs::parse(Direction::Fetch, options.refspecs.iter())
            .map_err(|error| TransferError::Configuration(error.to_string()))?;
        // Forced refspecs may replace any existing destination, as with `git fetch`.
        let authorized: BTreeSet<RefName> = listed
            .iter()
            .map(|reference| reference.name.clone())
            .collect();
        // Like `git fetch`, follow `core.logAllRefUpdates`: references outside its scope are
        // logged only when they already have a log.
        let mut logged = None;
        let reflog = match &options.reflog {
            None => Reflog::Preserve,
            Some((committer, message)) => {
                let (committer, message) = (committer.clone(), message.clone());
                match self
                    .reflog_scope()
                    .map_err(|error| TransferError::Configuration(error.to_string()))?
                {
                    ReflogScope::All => Reflog::AppendIfChanged { committer, message },
                    scope => {
                        if scope == ReflogScope::Conventional {
                            logged = Some(Reflog::AppendIfChanged {
                                committer: committer.clone(),
                                message: message.clone(),
                            });
                        }
                        Reflog::AppendExistingIfChanged { committer, message }
                    }
                }
            }
        };
        let mut request =
            FetchRequest::prepare_listed(self.clone(), specs, authorized, reflog, listed)
                .map_err(|error| TransferError::Fetch(Box::new(error.into())))?;
        if let Some(logged) = logged {
            for namespace in CONVENTIONAL {
                #[expect(clippy::expect_used, reason = "constant reference names are valid")]
                let namespace = RefName::new(namespace.strip_suffix(b"/").unwrap_or(namespace))
                    .expect("valid name");
                // Pruning a remote-tracking reference deletes its log, as below.
                request =
                    request.with_reflog_for_namespace(namespace, logged.clone(), Reflog::Delete);
            }
        }
        if options.prune {
            // Pruned references lose their reflogs, as in Git.
            request = request.with_prune();
            #[expect(clippy::expect_used, reason = "constant reference name is valid")]
            let namespaces = std::iter::once(RefName::new("refs/remotes").expect("valid name"))
                .chain(options.tag_namespaces.iter().cloned());
            for namespace in namespaces {
                request = request.with_reflog_for_update_kind(
                    namespace,
                    FetchUpdateKind::Prune,
                    Reflog::Delete,
                );
            }
        }
        for namespace in &options.tag_namespaces {
            request = request.with_tag_destination_namespace(namespace.clone());
        }
        if let Some(depth) = options.depth {
            request = request.with_depth(depth);
        }
        Ok(request)
    }

    fn push(
        &self,
        remote_name: &str,
        commands: Vec<PushCommand>,
        options: &PushOptions,
        environment: &Environment,
        callbacks: &mut dyn TransferCallbacks,
    ) -> Result<PushReport, TransferError> {
        self.push_observed(
            remote_name,
            commands,
            options,
            environment,
            callbacks,
            &|| {},
        )
    }

    /// Runs [`Self::push`], calling `before_prepare` before each preparation attempt.
    fn push_observed(
        &self,
        remote_name: &str,
        commands: Vec<PushCommand>,
        options: &PushOptions,
        environment: &Environment,
        callbacks: &mut dyn TransferCallbacks,
        before_prepare: &dyn Fn(),
    ) -> Result<PushReport, TransferError> {
        let (endpoint, destination) =
            self.endpoint(remote_name, Direction::Push, environment, &*callbacks)?;
        let hooks = match options.hooks {
            crate::hooks::Policy::Ignore => None,
            _ => Some(
                crate::hooks::Hooks::new(self, environment)
                    .map_err(|error| TransferError::Hook(Box::new(error)))?,
            ),
        };
        let pre_push = PrePush {
            hooks: hooks.as_ref(),
            policy: options.hooks,
            remote: remote_name,
            url: destination.bytes(),
            commands: &commands,
            ran: std::cell::Cell::new(false),
            failure: std::cell::RefCell::new(None),
        };
        let objects = self
            .objects_with(crate::PackLimits::trusted())
            .map_err(TransferError::local)?;
        let format = objects.object_format();
        let mut limits = PushLimits::trusted();
        if let Some(compression) = options.compression {
            limits.compression = compression;
        }
        let cancel = AtomicBool::new(false);
        let control = TransportControl::new(&cancel);
        // Each transport reads the receiver's advertisement before preparing. Like `git
        // send-pack`, preparation excludes the history of every advertised object (`roots`), so
        // the pack holds only what the receiver lacks.
        let callbacks = std::cell::RefCell::new(callbacks);
        // The source snapshot is needed only to prepare. Preparing takes it, so its mapped
        // indexes and cached delta bases are released before the receiver validates and installs
        // the pack, rather than holding both repositories' storage at once. A retry refills it.
        let source = std::cell::RefCell::new(Some(objects));
        let refill = || -> Result<(), TransferError> {
            let mut source = source.borrow_mut();
            if source.is_none() {
                *source = Some(
                    self.objects_with(crate::PackLimits::trusted())
                        .map_err(TransferError::local)?,
                );
            }
            Ok(())
        };
        let prepare = |roots: &[ObjectId],
                       current: Vec<Option<ObjectId>>|
         -> Result<PreparedPush, PushFailure> {
            pre_push.run(&current, format)?;
            before_prepare();
            // Every transport prepares at most once per send, and each retry refills first.
            let objects = source
                .borrow_mut()
                .take()
                .ok_or(PushFailure::Unsupported("preparing one push attempt twice"))?;
            let prepared = PreparedPush::new_with_progress(
                &objects,
                commands.clone(),
                roots,
                limits,
                &cancel,
                |event| callbacks.borrow_mut().push_progress(event),
            )?;
            let prepared = if options.push_options.is_empty() {
                prepared
            } else {
                prepared.with_push_options(options.push_options.clone())?
            };
            Ok(prepared.with_progress())
        };
        let names: Vec<RefName> = commands.iter().map(|c| c.name.clone()).collect();
        let result = match endpoint {
            Endpoint::Custom(custom) => {
                let connection = custom.connect(crate::transport::Service::ReceivePack)?;
                let advertised = std::cell::RefCell::new(BTreeMap::new());
                let result = crate::push::send_preparing(
                    &mut Half(&connection),
                    &mut Half(&connection),
                    format,
                    limits,
                    &cancel,
                    |advertisement| {
                        record_targets(advertisement, &names, &advertised);
                        let current = names
                            .iter()
                            .map(|name| advertisement.target(name))
                            .collect();
                        prepare(&advertisement.receiver_roots(), current)
                    },
                );
                // The service's failure explains an exchange that broke before anything was sent;
                // a local failure stays girt's own, and after a status report the report counts.
                let finished = connection.into_inner().finish();
                if let (
                    Err(crate::push::PushError::NotSent(
                        crate::push::PushFailure::Io(_) | crate::push::PushFailure::Protocol(_),
                    )),
                    Err(error),
                ) = (&result, finished)
                {
                    return Err(error.into());
                }
                result.map(|mut report| {
                    mark_up_to_date(&mut report, &advertised.into_inner());
                    report
                })
            }
            Endpoint::Local(path) => {
                let send = || {
                    crate::push::send_local_preparing_observed(
                        &path,
                        format,
                        control,
                        crate::push::ReceiverPolicy {
                            config_inputs: &crate::config::ConfigInputs::default(),
                            identity: options.identity.as_ref(),
                        },
                        |advertisement| {
                            let current = names
                                .iter()
                                .map(|name| advertisement.target(name))
                                .collect::<Result<_, _>>()?;
                            prepare(&advertisement.receiver_roots()?, current)
                        },
                        |event| callbacks.borrow_mut().validation_progress(event),
                    )
                };
                let mut result = send();
                // The destination's references changed while preparing: prepare once more against
                // the new ones. A second change is reported rather than retried.
                if is_knowledge_changed(&result) {
                    refill()?;
                    result = send();
                }
                // Receive hook output arrives with the report rather than live.
                if let Ok(report) = &result {
                    for message in &report.progress {
                        callbacks.borrow_mut().remote_message(message);
                    }
                }
                result
            }
            #[cfg(feature = "http")]
            Endpoint::Http(http) => {
                let runtime = runtime()?;
                let send = |remote: &crate::transport::http::HttpRemote,
                            callbacks: &std::cell::RefCell<&mut dyn TransferCallbacks>| {
                    let advertised = std::cell::RefCell::new(BTreeMap::new());
                    let result = runtime.block_on(crate::push::send_http_preparing(
                        remote,
                        format,
                        limits,
                        control,
                        |advertisement| {
                            record_targets(advertisement, &names, &advertised);
                            let current =
                                names.iter().map(|name| advertisement.target(name)).collect();
                            prepare(&advertisement.receiver_roots(), current)
                        },
                        |message| callbacks.borrow_mut().remote_message(message),
                    ));
                    result.map(|mut report| {
                        mark_up_to_date(&mut report, &advertised.into_inner());
                        report
                    })
                };
                let remote = http.remote(None)?;
                let mut result = send(&remote, &callbacks);
                http.settle_proxy(match &result {
                    Ok(_) => Ok(()),
                    Err(crate::push::PushError::NotSent(crate::push::PushFailure::Http(
                        crate::transport::http::HttpError::Status(status),
                    ))) => Err(Some(*status)),
                    Err(_) => Err(None),
                });
                if is_unauthorized_push(&result) {
                    let session = http.credentials(&mut **callbacks.borrow_mut())?;
                    let remote = http.remote(Some(session))?;
                    refill()?;
                    result = send(&remote, &callbacks);
                }
                result
            }
            #[cfg(all(feature = "ssh", any(target_os = "macos", target_os = "linux")))]
            Endpoint::Ssh(ssh) => {
                let runtime = runtime()?;
                let advertised = std::cell::RefCell::new(BTreeMap::new());
                let result = runtime.block_on(crate::push::send_ssh_preparing(
                    &ssh,
                    format,
                    limits,
                    control,
                    |advertisement| {
                        record_targets(advertisement, &names, &advertised);
                        let current = names
                            .iter()
                            .map(|name| advertisement.target(name))
                            .collect();
                        prepare(&advertisement.receiver_roots(), current)
                    },
                    |message| callbacks.borrow_mut().transport_message(message),
                    |message| callbacks.borrow_mut().remote_message(message),
                ));
                result.map(|mut report| {
                    mark_up_to_date(&mut report, &advertised.into_inner());
                    report
                })
            }
        };
        if let Some(error) = pre_push.failure.into_inner() {
            return Err(TransferError::Hook(Box::new(error)));
        }
        let report = result.map_err(|error| TransferError::Push(Box::new(error)))?;
        self.update_tracking_refs(remote_name, &report, options.identity.as_ref());
        Ok(report)
    }

    /// Updates local remote-tracking references for successfully pushed references, as `git
    /// push` does, using the remote's fetch refspecs. Failures are ignored: the next fetch
    /// corrects them.
    fn update_tracking_refs(
        &self,
        remote_name: &str,
        report: &PushReport,
        identity: Option<&crate::Signature>,
    ) {
        let Ok(Some(remote)) =
            crate::remote::ConfiguredRemote::find(self.config(), remote_name.as_bytes())
        else {
            return;
        };
        let Ok(refs) = self.references() else {
            return;
        };
        let succeeded = report.unpack == Some(crate::push::Status::Ok);
        for status in &report.refs {
            if !succeeded || status.status != Some(crate::push::Status::Ok) {
                continue;
            }
            let Some(name) = tracking_ref(remote.fetch_refspecs(), status.command.name.as_bytes())
            else {
                continue;
            };
            let deleted = status.command.deletes();
            let edit = crate::refs::RefEdit {
                name,
                dereference: crate::refs::Dereference::Stored,
                target: (!deleted).then_some(crate::refs::Target::Direct(status.command.new)),
                expected: crate::refs::Expected::Any,
                reflog: match (deleted, identity) {
                    (true, _) => Reflog::Delete,
                    (false, Some(identity)) => Reflog::AppendIfChanged {
                        committer: identity.clone(),
                        message: b"update by push".to_vec(),
                    },
                    (false, None) => Reflog::Preserve,
                },
            };
            // Applied independently so one conflicting name doesn't block the others.
            let _ = refs.transaction(std::slice::from_ref(&edit));
        }
    }
}

/// Maps a remote reference name through fetch refspecs to its remote-tracking reference.
fn tracking_ref(refspecs: &[crate::remote::ConfiguredRefspec], name: &[u8]) -> Option<RefName> {
    use crate::remote::ConfiguredRefspecKind;
    let matches = |pattern: &[u8]| -> Option<Vec<u8>> {
        match crate::bytes::split_once(pattern, b'*') {
            None => (pattern == name).then(Vec::new),
            Some((prefix, suffix)) => name
                .strip_prefix(prefix)?
                .strip_suffix(suffix)
                .map(<[u8]>::to_vec),
        }
    };
    let excluded = refspecs.iter().any(|spec| {
        spec.kind() == ConfiguredRefspecKind::Exclusion && spec.source().and_then(matches).is_some()
    });
    if excluded {
        return None;
    }
    refspecs
        .iter()
        .filter(|spec| spec.kind() == ConfiguredRefspecKind::Mapping)
        .find_map(|spec| {
            let captured = matches(spec.source()?)?;
            let destination = spec.destination()?;
            let destination = match crate::bytes::split_once(destination, b'*') {
                None => destination.to_vec(),
                Some((prefix, suffix)) => [prefix, &captured, suffix].concat(),
            };
            RefName::new(destination).ok()
        })
}

/// Records the advertised values of the pushed references.
/// The `pre-push` hook of one push, run once after the receiver's references are known.
struct PrePush<'a> {
    hooks: Option<&'a crate::hooks::Hooks>,
    policy: crate::hooks::Policy,
    remote: &'a str,
    url: &'a [u8],
    commands: &'a [PushCommand],
    ran: std::cell::Cell<bool>,
    failure: std::cell::RefCell<Option<crate::hooks::Error>>,
}

impl PrePush<'_> {
    /// Runs the hook the first time a transport reports the receiver's `current` values, one per
    /// command. Commands whose expectation already differs from the receiver, or that would not
    /// change it, are left out, as Git leaves out rejected and up-to-date references.
    fn run(
        &self,
        current: &[Option<ObjectId>],
        format: crate::ObjectFormat,
    ) -> Result<(), PushFailure> {
        let Some(hooks) = self.hooks else {
            return Ok(());
        };
        if self.ran.replace(true) {
            return Ok(());
        }
        let null = ObjectId::null(format);
        let mut stdin = Vec::new();
        for (command, current) in self.commands.iter().zip(current) {
            if command.expected != *current || *current == Some(command.new) {
                continue;
            }
            let deletes = command.new == null;
            if deletes && current.is_none() {
                continue;
            }
            let local = if deletes {
                "(delete)".to_owned()
            } else {
                command.new.to_string()
            };
            stdin.extend_from_slice(format!("{local} {} ", command.new).as_bytes());
            stdin.extend_from_slice(command.name.as_bytes());
            stdin.extend_from_slice(format!(" {}\n", current.unwrap_or(null)).as_bytes());
        }
        let invocation = crate::hooks::Invocation::new()
            .with_argument(self.remote)
            .with_argument(crate::hooks::os_string(self.url))
            .with_stdin(stdin);
        let cancel = AtomicBool::new(false);
        match hooks.run_blocking(
            "pre-push",
            &invocation,
            self.policy,
            TransportControl::new(&cancel),
        ) {
            Ok(_) => Ok(()),
            Err(error) => {
                *self.failure.borrow_mut() = Some(error);
                Err(PushFailure::Unsupported(
                    "push stopped by the pre-push hook",
                ))
            }
        }
    }
}

fn record_targets(
    advertisement: &crate::push::PushAdvertisement,
    names: &[RefName],
    advertised: &std::cell::RefCell<BTreeMap<RefName, Option<ObjectId>>>,
) {
    let mut advertised = advertised.borrow_mut();
    for name in names {
        advertised.insert(name.clone(), advertisement.target(name));
    }
}

/// Like Git, treats a rejected reference whose remote value already equals the requested value as
/// up to date.
fn mark_up_to_date(report: &mut PushReport, advertised: &BTreeMap<RefName, Option<ObjectId>>) {
    for status in &mut report.refs {
        let Some(current) = advertised.get(&status.command.name) else {
            continue;
        };
        // Deletions are never up to date; see `git push --force-with-lease`.
        let up_to_date = !status.command.deletes() && *current == Some(status.command.new);
        if up_to_date && status.status != Some(crate::push::Status::Ok) {
            status.status = Some(crate::push::Status::Ok);
            status.rejection_origin = None;
        }
    }
}

fn is_knowledge_changed<T>(result: &Result<T, crate::push::PushError>) -> bool {
    matches!(
        result,
        Err(crate::push::PushError::NotSent(
            crate::push::PushFailure::KnowledgeChanged(_)
        ))
    )
}

#[cfg(feature = "http")]
fn is_unauthorized_push<T>(result: &Result<T, crate::push::PushError>) -> bool {
    matches!(
        result,
        Err(crate::push::PushError::NotSent(
            crate::push::PushFailure::Http(crate::transport::http::HttpError::Status(401))
        ))
    )
}

/// Reads `remote.<name>.partialclonefilter`, the filter a partial clone keeps using.
fn configured_filter(
    config: &crate::Config,
    remote_name: &str,
) -> Result<Option<ObjectFilter>, TransferError> {
    let Some(spec) = config.string("remote", Some(remote_name.as_bytes()), "partialclonefilter")
    else {
        return Ok(None);
    };
    let invalid = |detail: String| {
        TransferError::Configuration(format!(
            "invalid remote.{remote_name}.partialclonefilter: {detail}"
        ))
    };
    let spec = std::str::from_utf8(spec).map_err(|error| invalid(error.to_string()))?;
    spec.parse()
        .map(Some)
        .map_err(|error: crate::fetch::ObjectFilterParseError| invalid(error.to_string()))
}

// The HTTP status a fetch failed with, for `Http::settle_proxy`.
#[cfg(feature = "http")]
fn fetch_status<T>(result: &Result<T, crate::fetch::FetchError>) -> Result<(), Option<u16>> {
    result.as_ref().map(|_| ()).map_err(status_of)
}

#[cfg(feature = "http")]
fn status_of(error: &crate::fetch::FetchError) -> Option<u16> {
    match error {
        crate::fetch::FetchError::Http(crate::transport::http::HttpError::Status(status)) => {
            Some(*status)
        }
        _ => None,
    }
}

#[cfg(feature = "http")]
fn is_unauthorized_fetch<T>(result: &Result<T, crate::fetch::FetchError>) -> bool {
    matches!(
        result,
        Err(crate::fetch::FetchError::Http(
            crate::transport::http::HttpError::Status(401)
        ))
    )
}

#[cfg(any(
    feature = "http",
    all(feature = "ssh", any(target_os = "macos", target_os = "linux"))
))]
fn runtime() -> Result<tokio::runtime::Runtime, TransferError> {
    tokio::runtime::Builder::new_current_thread()
        .enable_all()
        .build()
        .map_err(TransferError::local)
}

#[cfg(test)]
mod tests {
    use std::cell::Cell;
    use std::path::{Path, PathBuf};
    use std::process::Command;

    use super::*;
    use crate::push::{ForcePolicy, PushError};

    fn git(directory: &Path, args: &[&str], date: usize) -> String {
        let date = format!("@{} +0000", 1_700_000_000 + date * 60);
        let output = Command::new("git")
            .current_dir(directory)
            .env_clear()
            .env("PATH", std::env::var_os("PATH").unwrap())
            .env("GIT_CONFIG_NOSYSTEM", "1")
            .env("GIT_CONFIG_GLOBAL", "/dev/null")
            .env("GIT_AUTHOR_NAME", "Push Author")
            .env("GIT_AUTHOR_EMAIL", "push@example.com")
            .env("GIT_COMMITTER_NAME", "Push Author")
            .env("GIT_COMMITTER_EMAIL", "push@example.com")
            .env("GIT_AUTHOR_DATE", &date)
            .env("GIT_COMMITTER_DATE", &date)
            .args(args)
            .output()
            .expect("Git required for push fixtures");
        assert!(
            output.status.success(),
            "git {args:?}: {}",
            String::from_utf8_lossy(&output.stderr)
        );
        String::from_utf8(output.stdout).unwrap().trim().to_owned()
    }

    /// A worktree whose `main` has 30 commits, each adding a file, pushed to a bare `origin`, and
    /// a `topic` branch one commit ahead of `main` that the destination lacks.
    fn fixture() -> (tempfile::TempDir, PathBuf, PathBuf, ObjectId) {
        let root = tempfile::tempdir().unwrap();
        let work = root.path().join("work");
        let dest = root.path().join("dest.git");
        std::fs::create_dir(&work).unwrap();
        std::fs::create_dir(&dest).unwrap();
        git(&work, &["init", "-q", "--initial-branch=main", "."], 0);
        git(&dest, &["init", "-q", "--bare", "."], 0);
        git(&dest, &["config", "receive.unpackLimit", "1"], 0);
        for n in 0..=30 {
            if n == 30 {
                git(&work, &["push", "-q", &dest.to_string_lossy(), "main"], n);
                git(&work, &["switch", "-q", "-c", "topic"], n);
            }
            std::fs::write(work.join(format!("file-{n}")), format!("{n}\n")).unwrap();
            git(&work, &["add", "."], n);
            git(&work, &["commit", "-q", "-m", &n.to_string()], n);
        }
        git(
            &work,
            &["remote", "add", "origin", &dest.to_string_lossy()],
            0,
        );
        let topic = git(&work, &["rev-parse", "topic"], 0).parse().unwrap();
        (root, work, dest, topic)
    }

    fn push(
        work: &Path,
        topic: ObjectId,
        before_prepare: &dyn Fn(),
    ) -> Result<PushReport, TransferError> {
        Repository::open(work).unwrap().push_observed(
            "origin",
            vec![PushCommand {
                name: RefName::new("refs/heads/topic").unwrap(),
                expected: None,
                new: topic,
                force: ForcePolicy::FastForwardOnly,
            }],
            &PushOptions::default(),
            &Environment::default(),
            &mut NoCallbacks,
            before_prepare,
        )
    }

    /// Pack identities independently listed by Git, including verified thin-pack repair bases.
    fn pack_ids(dest: &Path) -> std::collections::BTreeMap<PathBuf, Vec<String>> {
        std::fs::read_dir(dest.join("objects/pack"))
            .unwrap()
            .map(|entry| entry.unwrap().path())
            .filter(|path| path.extension().is_some_and(|e| e == "idx"))
            .map(|index| {
                let output = Command::new("git")
                    .arg("show-index")
                    .stdin(std::fs::File::open(&index).unwrap())
                    .output()
                    .unwrap();
                assert!(output.status.success());
                let ids = String::from_utf8(output.stdout)
                    .unwrap()
                    .lines()
                    .map(|line| line.split_whitespace().nth(1).unwrap().to_owned())
                    .collect();
                (index, ids)
            })
            .collect()
    }

    fn packed(dest: &Path) -> usize {
        pack_ids(dest).values().map(Vec::len).sum()
    }

    #[test]
    fn push_retry_after_knowledge_change_reuses_advertisement() {
        let (_root, work, dest, topic) = fixture();
        let before = pack_ids(&dest);
        let base_tree = git(&work, &["rev-parse", "main~1^{tree}"], 0);
        let attempts = Cell::new(0);
        // The destination's only ref moves back one commit while the first pack is prepared, so
        // the root that pack relies on is no longer advertised.
        let report = push(&work, topic, &|| {
            attempts.set(attempts.get() + 1);
            if attempts.get() == 1 {
                git(&dest, &["update-ref", "refs/heads/main", "main~1"], 0);
            }
        })
        .unwrap();
        assert!(report.all_succeeded(), "{report:?}");
        assert_eq!(attempts.get(), 2);
        // The retry sends exactly Git's six selected objects. Native thin-pack repair additionally
        // appends the verified old tree base, rather than retransmitting receiver history.
        let after = pack_ids(&dest);
        let mut incoming: Vec<_> = after
            .iter()
            .filter(|(path, _)| !before.contains_key(*path))
            .flat_map(|(_, ids)| ids.iter().cloned())
            .collect();
        let oracle = git(
            &work,
            &["rev-list", "--objects", "topic", "--not", "main~1"],
            0,
        );
        let mut expected: Vec<_> = oracle
            .lines()
            .map(|line| line.split_whitespace().next().unwrap().to_owned())
            .collect();
        assert_eq!(expected.len(), 6);
        expected.push(base_tree);
        incoming.sort();
        expected.sort();
        assert_eq!(incoming, expected);
        assert_eq!(git(&dest, &["rev-parse", "topic"], 0), topic.to_string());
        git(&dest, &["fsck", "--strict", "--no-dangling"], 0);
    }

    #[test]
    fn push_reports_a_second_knowledge_change_without_sending() {
        let (_root, work, dest, topic) = fixture();
        let before = packed(&dest);
        let attempts = Cell::new(0);
        let result = push(&work, topic, &|| {
            attempts.set(attempts.get() + 1);
            git(&dest, &["update-ref", "refs/heads/main", "main~1"], 0);
        });
        assert!(
            matches!(
                result,
                Err(TransferError::Push(ref error))
                    if matches!(**error, PushError::NotSent(PushFailure::KnowledgeChanged(_)))
            ),
            "{result:?}"
        );
        assert_eq!(attempts.get(), 2);
        assert_eq!(packed(&dest), before);
        assert!(git(&dest, &["for-each-ref", "refs/heads/topic"], 0).is_empty());
    }

    #[cfg(feature = "http")]
    #[test]
    fn native_store_accepts_plain_paths_and_leaves_shell_syntax_to_git() {
        let environment = Environment::default()
            .with("HOME", "/home/user")
            .with_current_dir("/work");
        let files = |text| native_store(text, &environment).map(|store| store.files().to_vec());
        assert_eq!(
            files("store --file=~/creds"),
            Some(vec![PathBuf::from("/home/user/creds")])
        );
        assert_eq!(
            files("store --file creds"),
            Some(vec![PathBuf::from("/work/creds")])
        );
        assert_eq!(files("store").map(|files| files.len()), Some(2));
        for text in [
            "store --file=creds>out",
            "store --file creds|tee",
            "store --file=a;b",
            "store --file=$HOME/creds",
            "store --file='creds'",
            "store --file=(creds)",
            "store --file=a&",
            "store --file=<in",
            "store --other",
            "store --file a b",
            "store>out",
        ] {
            assert!(files(text).is_none(), "{text}");
        }
    }

    #[test]
    fn tracking_ref_rejects_overlapping_pattern_halves() {
        use crate::remote::{ConfiguredRefspec, Direction};
        let refspecs =
            [
                ConfiguredRefspec::parse(Direction::Fetch, b"refs/heads/*/x:refs/remotes/o/*")
                    .unwrap(),
            ];
        assert_eq!(tracking_ref(&refspecs, b"refs/heads/x"), None);
        assert_eq!(
            tracking_ref(&refspecs, b"refs/heads/a/x")
                .unwrap()
                .as_bytes(),
            b"refs/remotes/o/a"
        );
    }
}

#[cfg(test)]
#[path = "transfer_fetch_tests.rs"]
mod fetch_tests;

#[cfg(test)]
#[path = "transfer_pack_tests.rs"]
mod pack_tests;