gix 0.89.0

use gix_error::ResultExt;

use crate::{Result, bstr::BString, remote};

#[cfg(feature = "async-network-client")]
use gix_transport::client::async_io::Transport;
#[cfg(feature = "blocking-network-client")]
use gix_transport::client::blocking_io::Transport;

type ConfigureRemoteFn = Box<dyn FnMut(crate::Remote<'_>) -> Result<crate::Remote<'_>>>;
#[cfg(any(feature = "async-network-client", feature = "blocking-network-client"))]
type ConfigureConnectionFn = Box<dyn FnMut(&mut remote::Connection<'_, '_, '_, Box<dyn Transport + Send>>) -> Result>;

/// A utility to collect configuration on how to fetch from a remote and initiate a fetch operation. It will delete the newly
/// created repository on when dropped without successfully finishing a fetch.
#[must_use]
pub struct PrepareFetch {
    /// A freshly initialized repository which is owned by us, or `None` if it was handed to the user
    repo: Option<crate::Repository>,
    /// The name of the remote, which defaults to `origin` if not overridden.
    remote_name: Option<BString>,
    /// Additional config `values` that are applied in-memory before starting the fetch process.
    config_overrides: Vec<BString>,
    /// A function to configure a remote prior to fetching a pack.
    configure_remote: Option<ConfigureRemoteFn>,
    /// A function to configure a connection before using it.
    #[cfg(any(feature = "async-network-client", feature = "blocking-network-client"))]
    configure_connection: Option<ConfigureConnectionFn>,
    /// Options for preparing a fetch operation.
    #[cfg(any(feature = "async-network-client", feature = "blocking-network-client"))]
    fetch_options: remote::ref_map::Options,
    /// The url to clone from
    #[cfg_attr(not(feature = "blocking-network-client"), allow(dead_code))]
    url: gix_url::Url,
    /// How to handle shallow clones
    #[cfg_attr(not(feature = "blocking-network-client"), allow(dead_code))]
    shallow: remote::fetch::Shallow,
    /// The name of the reference to fetch. If `None`, the reference pointed to by `HEAD` will be checked out.
    #[cfg_attr(not(feature = "blocking-network-client"), allow(dead_code))]
    ref_name: Option<gix_ref::PartialName>,
    /// The single revision to fetch and check out with a detached `HEAD`.
    #[cfg_attr(not(feature = "blocking-network-client"), allow(dead_code))]
    revision: Option<gix_refspec::RefSpec>,
    /// If `true`, drop removes the entire worktree. Otherwise leave it alone.
    remove_worktree_on_drop: bool,
}

/// Errors returned by [`PrepareFetch::with_revision()`].
pub mod with_revision {
    /// An invalid revision for a single-revision clone.
    #[derive(Debug)]
    #[expect(missing_docs)]
    pub enum Error {
        Parse(gix_error::Error),
        Invalid { revision: crate::bstr::BString },
    }

    impl std::fmt::Display for Error {
        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
            match self {
                Error::Parse(err) => err.fmt(f),
                Error::Invalid { revision } => write!(
                    f,
                    "A clone revision must be HEAD, a full reference name, or a full object ID, got {revision:?}"
                ),
            }
        }
    }

    impl std::error::Error for Error {
        fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
            match self {
                Error::Parse(err) => Some(err),
                Error::Invalid { .. } => Some(const { &gix_error::ClassificationMarker::VALIDATION }),
            }
        }
    }

    impl From<gix_error::Exn<gix_error::Message>> for Error {
        fn from(err: gix_error::Exn<gix_error::Message>) -> Self {
            Error::Parse(err.into_error())
        }
    }
}

/// Instantiation
impl PrepareFetch {
    /// Create a new repository at `path` with `create_opts` which is ready to clone from `url`, possibly after making additional adjustments to
    /// configuration and settings.
    ///
    /// Note that this is merely a handle to perform the actual connection to the remote, and if any of it fails the freshly initialized repository
    /// will be removed automatically as soon as this instance drops.
    ///
    /// # Deviation
    ///
    /// Unlike `git clone`, repository-local environment overrides such as `GIT_WORK_TREE` and `GIT_INDEX_FILE` are ignored.
    /// This prevents cloning from a Git hook from writing the clone's index or files into the caller's repository.
    /// Editor and notes preferences (`GIT_EDITOR` and `GIT_NOTES_REF`) are still honored.
    ///
    /// Similar to `git`, a missing user name and email configuration is not terminal and we will fill it in with dummy values. However,
    /// instead of deriving values from the system, ours are hardcoded to indicate what happened.
    pub fn new<Url, E>(
        url: Url,
        path: impl AsRef<std::path::Path>,
        kind: crate::create::Kind,
        create_opts: crate::create::Options,
        open_opts: crate::open::Options,
    ) -> Result<Self>
    where
        Url: TryInto<gix_url::Url, Error = E>,
        E: std::error::Error + Send + Sync + 'static,
    {
        Self::new_inner(url.try_into().or_error()?, path.as_ref(), kind, create_opts, open_opts)
    }
    fn new_inner(
        mut url: gix_url::Url,
        path: &std::path::Path,
        kind: crate::create::Kind,
        mut create_opts: crate::create::Options,
        open_opts: crate::open::Options,
    ) -> Result<Self> {
        // Keep inherited repository paths from redirecting this clone into the caller's repository.
        let mut open_opts = open_opts.without_repository_environment_overrides();
        if create_opts.destination_must_be_empty.is_none() {
            create_opts.destination_must_be_empty = Some(true);
        }

        let git_dir = match kind {
            crate::create::Kind::WithWorktree => path.join(gix_discover::DOT_GIT_DIR),
            crate::create::Kind::Bare => path.to_owned(),
        };
        let config = crate::config(Some(&git_dir), &open_opts)?;
        if crate::config::cache::util::config_bool_opt(
            &config,
            &crate::config::tree::Core::SYMLINKS,
            "core.symlinks",
            open_opts.lenient_config,
        )? == Some(false)
        {
            open_opts.api_config_overrides.push("core.symlinks=false".into());
        }

        // Capture this before init_opts creates `.git`, otherwise the check below would see our own files.
        let remove_worktree_on_drop = match std::fs::read_dir(path) {
            Ok(mut entries) => entries.next().is_none(),
            // Non-existent destinations will be created by init_opts.
            Err(err) if err.kind() == std::io::ErrorKind::NotFound => true,
            // If we can't verify emptiness, keep cleanup conservative and leave the destination untouched.
            Err(_) => false,
        };

        let mut repo = crate::ThreadSafeRepository::init_opts(path, kind, create_opts, open_opts)?.to_thread_local();
        url.canonicalize(repo.options.current_dir_or_empty()).or_raise(|| {
            gix_error::message!(
                "Failed to turn the relative file url {:?} into an absolute one",
                url.to_bstring()
            )
        })?;
        repo.committer_or_set_generic_fallback()?;
        Ok(PrepareFetch {
            url,
            #[cfg(any(feature = "async-network-client", feature = "blocking-network-client"))]
            fetch_options: Default::default(),
            repo: Some(repo),
            config_overrides: Vec::new(),
            remote_name: None,
            configure_remote: None,
            #[cfg(any(feature = "async-network-client", feature = "blocking-network-client"))]
            configure_connection: None,
            shallow: remote::fetch::Shallow::NoChange,
            ref_name: None,
            revision: None,
            remove_worktree_on_drop,
        })
    }
}

/// A utility to collect configuration on how to perform a checkout into a working tree,
/// and when dropped without checking out successfully the fetched repository will be deleted from disk.
#[must_use]
#[cfg(feature = "worktree-mutation")]
#[derive(Debug)]
pub struct PrepareCheckout {
    /// A freshly initialized repository which is owned by us, or `None` if it was successfully checked out.
    pub(self) repo: Option<crate::Repository>,
    /// The name of the reference to check out. If `None`, the reference pointed to by `HEAD` will be checked out.
    pub(self) ref_name: Option<gix_ref::PartialName>,
    /// If `true`, drop removes the entire worktree. Otherwise leave it alone.
    pub(self) remove_worktree_on_drop: bool,
}

fn cleanup_clone_destination_on_drop(repo: &crate::Repository, remove_worktree_on_drop: bool) {
    let path_to_remove = if remove_worktree_on_drop {
        Some(repo.workdir().unwrap_or_else(|| repo.path()))
    } else {
        // The destination held pre-existing user files. Leave everything, including the `.git` we created,
        // so the user can inspect or clean up the partially cloned repository with Git tooling.
        None
    };
    if let Some(path_to_remove) = path_to_remove {
        std::fs::remove_dir_all(path_to_remove).ok();
    }
}

// This module encapsulates functionality that works with both feature toggles. Can be combined with `fetch`
// once async and clone are a thing.
#[cfg(any(feature = "async-network-client", feature = "blocking-network-client"))]
mod access_feat {
    use super::Transport;
    use crate::Result;
    use crate::clone::PrepareFetch;

    /// Builder
    impl PrepareFetch {
        /// Set a callback to use for configuring the connection to use right before connecting to the remote.
        ///
        /// It is most commonly used for custom configuration.
        // TODO: tests
        pub fn configure_connection(
            mut self,
            f: impl FnMut(&mut crate::remote::Connection<'_, '_, '_, Box<dyn Transport + Send>>) -> Result + 'static,
        ) -> Self {
            self.configure_connection = Some(Box::new(f));
            self
        }

        /// Set additional options to adjust parts of the fetch operation that are not affected by the git configuration.
        pub fn with_fetch_options(mut self, opts: crate::remote::ref_map::Options) -> Self {
            self.fetch_options = opts;
            self
        }
    }
}

///
#[cfg(any(feature = "async-network-client-async-std", feature = "blocking-network-client"))]
pub mod fetch;

mod access;

///
#[cfg(feature = "worktree-mutation")]
pub mod checkout;