ephemeris_release/

git.rs

//! Git adapters for local release operations, served through libgit2.

use std::cell::RefCell;
use std::error::Error as StdError;
use std::path::{Path, PathBuf};

use ephemeris_files::RepositoryPath;
use ephemeris_token::Token;
use git2::{
    BranchType, Commit, Cred, CredentialType, DiffOptions, Direction, Error as Git2Error,
    ErrorCode, FetchOptions, Oid, ProxyOptions, PushOptions, Remote, RemoteCallbacks, RemoteHead,
    Repository, Signature, Sort, Tree, WorktreeAddOptions, WorktreePruneOptions, message_prettify,
};

use crate::{Author, GitCommands, GitRefs};

/// The remote every release operation fetches from and pushes to.
const ORIGIN: &str = "origin";

/// A Git query or mutation failure.
#[derive(Debug, thiserror::Error)]
pub enum GitError {
    /// The directory is not a Git repository or worktree libgit2 can open.
    #[error("cannot open the Git repository at {}", path.display())]
    Open {
        /// The directory.
        path: PathBuf,
        /// The libgit2 failure.
        #[source]
        source: Git2Error,
    },
    /// The tag names could not be read.
    #[error("cannot list tags")]
    Tags(#[source] Git2Error),
    /// A revision expression does not name a commit.
    #[error("cannot resolve revision {revision:?}")]
    Resolve {
        /// The revision expression.
        revision: String,
        /// The libgit2 failure.
        #[source]
        source: Git2Error,
    },
    /// A reference exists but cannot be read or peeled to a commit.
    #[error("cannot read reference {name:?}")]
    Reference {
        /// The full reference name.
        name: String,
        /// The libgit2 failure.
        #[source]
        source: Git2Error,
    },
    /// The ancestry of two commits could not be read.
    #[error("cannot tell whether {ancestor} is an ancestor of {descendant}")]
    Ancestry {
        /// The possible ancestor.
        ancestor: String,
        /// The possible descendant.
        descendant: String,
        /// The libgit2 failure.
        #[source]
        source: Git2Error,
    },
    /// Two commits could not be compared.
    #[error("cannot compare {paths:?} between {} and {to}", from.as_deref().unwrap_or("the root"))]
    Diff {
        /// The older revision, absent for the empty tree.
        from: Option<String>,
        /// The newer revision.
        to: String,
        /// The repository paths the comparison is limited to.
        paths: Vec<PathBuf>,
        /// The libgit2 failure.
        #[source]
        source: Git2Error,
    },
    /// The commits between two revisions could not be listed.
    #[error(
        "cannot list the commits that change {paths:?} between {} and {to}",
        from.as_deref().unwrap_or("the root")
    )]
    History {
        /// The older revision, absent for the whole history.
        from: Option<String>,
        /// The newer revision.
        to: String,
        /// The repository paths the commits are limited to.
        paths: Vec<PathBuf>,
        /// The libgit2 failure.
        #[source]
        source: Git2Error,
    },
    /// The named remote is not configured.
    #[error("cannot find remote {name:?}")]
    Remote {
        /// The remote name.
        name: String,
        /// The libgit2 failure.
        #[source]
        source: Git2Error,
    },
    /// A fetch failed.
    #[error("cannot fetch {refspec:?} from {remote:?}")]
    Fetch {
        /// The remote name.
        remote: String,
        /// The requested refspec.
        refspec: String,
        /// The libgit2 failure.
        #[source]
        source: Git2Error,
    },
    /// A disposable worktree could not be created.
    #[error("cannot create a worktree at {}", path.display())]
    WorktreeAdd {
        /// The worktree directory.
        path: PathBuf,
        /// The libgit2 failure.
        #[source]
        source: Git2Error,
    },
    /// A disposable worktree could not be removed.
    #[error("cannot remove the worktree at {}", path.display())]
    WorktreeRemove {
        /// The worktree directory.
        path: PathBuf,
        /// The libgit2 failure.
        #[source]
        source: Git2Error,
    },
    /// The worktree could not be pruned and its branch could not be deleted.
    #[error(
        "cannot prune the worktree at {} ({prune}), and cannot delete its branch: {branch}",
        path.display()
    )]
    WorktreeRemoveFailed {
        /// The worktree directory.
        path: PathBuf,
        /// The prune failure.
        #[source]
        prune: Git2Error,
        /// The branch deletion failure.
        branch: Git2Error,
    },
    /// Worktree changes could not be staged.
    #[error("cannot stage changes in {}", worktree.display())]
    Stage {
        /// The worktree.
        worktree: PathBuf,
        /// The libgit2 failure.
        #[source]
        source: Git2Error,
    },
    /// The staged changes could not be committed.
    #[error("cannot commit in {}", worktree.display())]
    Commit {
        /// The worktree.
        worktree: PathBuf,
        /// The libgit2 failure.
        #[source]
        source: Git2Error,
    },
    /// An annotated tag could not be created.
    #[error("cannot create tag {tag:?}")]
    Tag {
        /// The tag name.
        tag: String,
        /// The libgit2 failure.
        #[source]
        source: Git2Error,
    },
    /// The remote reference heads could not be listed.
    #[error("cannot list the references of remote {remote:?}")]
    List {
        /// The remote name.
        remote: String,
        /// The libgit2 failure.
        #[source]
        source: Git2Error,
    },
    /// The remote branch moved away from the head the push expected.
    #[error("remote {reference} is at {actual:?}, expected {expected:?}")]
    StaleLease {
        /// The full remote reference name.
        reference: String,
        /// The head the push was based on; `None` requires the branch to be
        /// absent.
        expected: Option<String>,
        /// The head on the remote; `None` when the branch is absent.
        actual: Option<String>,
    },
    /// The push could not be sent.
    #[error("cannot push {reference}")]
    Push {
        /// The full remote reference name.
        reference: String,
        /// The libgit2 failure.
        #[source]
        source: Git2Error,
    },
    /// The remote refused a reference update.
    #[error("the remote rejected the update of {reference}: {status}")]
    Rejected {
        /// The full remote reference name.
        reference: String,
        /// The status the remote reported.
        status: String,
    },
}

/// The repository paths whose changes count for a unit: everything under
/// the `source` directories except the unit changelog.
#[derive(Clone, Copy, Debug)]
pub struct UnitScope<'a> {
    /// Repository directories whose changes trigger a release.
    pub source: &'a [RepositoryPath],
    /// Repository path of the unit changelog, which never counts.
    pub changelog: Option<&'a Path>,
}

impl UnitScope<'_> {
    fn paths(self) -> Vec<PathBuf> {
        self.source
            .iter()
            .map(|path| path.as_path().to_path_buf())
            .collect()
    }

    /// Whether the trees `old` and `new` differ in a path of this scope.
    fn differs(
        self,
        repo: &Repository,
        old: Option<&Tree<'_>>,
        new: &Tree<'_>,
    ) -> Result<bool, Git2Error> {
        let mut options = DiffOptions::new();
        let is_root = |path: &RepositoryPath| {
            path.as_path().as_os_str().is_empty() || path.as_path() == Path::new(".")
        };
        if !self.source.iter().any(is_root) {
            for path in self.source {
                options.pathspec(path.as_path());
            }
        }
        let diff = repo.diff_tree_to_tree(old, Some(new), Some(&mut options))?;
        Ok(diff.deltas().any(|delta| {
            [delta.old_file(), delta.new_file()]
                .iter()
                .any(|file| file.path() != self.changelog)
        }))
    }
}

/// Read access to repository history.
pub trait GitHistory {
    /// The failure of a history read.
    type Error: StdError + Send + Sync + 'static;

    /// Messages of the commits after `from` up to `to` that change `scope`,
    /// oldest first. Without `from` the walk reaches the root commit. Merge
    /// commits are left out.
    fn commit_messages(
        &self,
        repository: &Path,
        from: Option<&str>,
        to: &str,
        scope: UnitScope<'_>,
    ) -> Result<Vec<String>, Self::Error>;
    /// Whether the first-parent chains from `base` to `first` and from `base`
    /// to `second` have the same length and the same trees and messages.
    /// A chain that does not reach `base` is equivalent to nothing.
    fn equivalent(
        &self,
        repository: &Path,
        base: &str,
        first: &str,
        second: &str,
    ) -> Result<bool, Self::Error>;
    /// Whether `scope` differs between the commits `from` and `to`. Without
    /// `from` the comparison starts from the empty tree.
    fn has_changes(
        &self,
        repository: &Path,
        from: Option<&str>,
        to: &str,
        scope: UnitScope<'_>,
    ) -> Result<bool, Self::Error>;
    /// Whether `ancestor` is `descendant` or reachable from it.
    fn is_ancestor(
        &self,
        repository: &Path,
        ancestor: &str,
        descendant: &str,
    ) -> Result<bool, Self::Error>;
    /// The commit a revision expression such as `origin/main` names.
    fn resolve(&self, repository: &Path, rev: &str) -> Result<String, Self::Error>;
    /// List the tag names that start with `prefix`.
    fn tags(&self, repository: &Path, prefix: &str) -> Result<Vec<String>, Self::Error>;
}

/// Repository changes that maintain a release proposal branch.
pub trait ProposalGit {
    /// The failure of a branch update.
    type Error: StdError + Send + Sync + 'static;

    /// Commit staged changes, returning the new commit hash, or `None` when
    /// nothing was staged.
    fn commit_if_staged(
        &self,
        worktree: &Path,
        message: &str,
        author: Author<'_>,
    ) -> Result<Option<String>, Self::Error>;
    /// Update local references from `origin` as `refspec` maps them.
    fn fetch(&self, repository: &Path, refspec: &str) -> Result<(), Self::Error>;
    /// Like `fetch`, but succeed when the remote has no reference named by
    /// `refspec`.
    fn fetch_if_present(&self, repository: &Path, refspec: &str) -> Result<(), Self::Error>;
    /// Push the worktree's `HEAD` to `branch`, failing if the remote branch
    /// has moved away from `expected`.
    fn push_with_lease(
        &self,
        worktree: &Path,
        branch: &str,
        expected: Option<&str>,
    ) -> Result<(), Self::Error>;
    /// Stage the changes at these worktree-relative paths, tracked or not.
    fn stage_update(&self, worktree: &Path, paths: &[PathBuf]) -> Result<(), Self::Error>;
    /// Create a disposable worktree at the not yet existing `path`, checked
    /// out to `baseline` on a private branch.
    fn worktree_add(
        &self,
        repository: &Path,
        path: &Path,
        baseline: &str,
    ) -> Result<(), Self::Error>;
    /// Remove a worktree created with [`ProposalGit::worktree_add`].
    fn worktree_remove(&self, repository: &Path, path: &Path) -> Result<(), Self::Error>;
}

/// The HTTPS credential pushes and fetches authenticate with.
#[derive(Clone, Debug)]
pub struct RemoteCredentials {
    username: String,
    token: Token,
}

/// Production Git adapter backed by libgit2.
#[derive(Clone, Debug, Default)]
pub struct SystemGit {
    credentials: Option<RemoteCredentials>,
}

impl RemoteCredentials {
    /// Authenticate as `username` with `token`.
    ///
    /// Forges differ in the username they require beside a token.
    #[must_use]
    pub fn new<U: Into<String>>(username: U, token: Token) -> Self {
        Self {
            username: username.into(),
            token,
        }
    }
}

impl SystemGit {
    /// An adapter that answers HTTPS authentication requests with
    /// `credentials`.
    #[must_use]
    pub const fn authenticated(credentials: RemoteCredentials) -> Self {
        Self {
            credentials: Some(credentials),
        }
    }

    /// Proxy settings taken from the Git configuration and environment, as
    /// the `git` command line uses them.
    fn proxy() -> ProxyOptions<'static> {
        let mut options = ProxyOptions::new();
        options.auto();
        options
    }

    fn open(path: &Path) -> Result<Repository, GitError> {
        Repository::open(path).map_err(|source| GitError::Open {
            path: path.to_path_buf(),
            source,
        })
    }

    /// The commit a revision expression names.
    fn commit<'r>(repo: &'r Repository, rev: &str) -> Result<Commit<'r>, Git2Error> {
        let object = repo.revparse_single(rev)?;
        object.peel_to_commit()
    }

    fn origin(repo: &Repository) -> Result<Remote<'_>, GitError> {
        repo.find_remote(ORIGIN).map_err(|source| GitError::Remote {
            name: ORIGIN.to_owned(),
            source,
        })
    }

    /// The worktree and private branch name for a worktree directory, derived
    /// from its path so that removal finds what creation registered.
    fn worktree_name(path: &Path) -> String {
        let mut name = String::from("ephemeris-worktree-");
        for component in path.components().rev().take(2) {
            name.extend(
                component
                    .as_os_str()
                    .to_string_lossy()
                    .chars()
                    .filter(char::is_ascii_alphanumeric),
            );
        }
        name
    }

    /// Callbacks that offer the configured credential once per connection,
    /// so a rejected token fails instead of being retried forever.
    fn callbacks(&self) -> RemoteCallbacks<'_> {
        let mut callbacks = RemoteCallbacks::new();
        if let Some(credentials) = &self.credentials {
            let mut offered = false;
            callbacks.credentials(move |_, _, allowed| {
                if offered || !allowed.contains(CredentialType::USER_PASS_PLAINTEXT) {
                    return Err(Git2Error::from_str(
                        "the configured forge token was rejected or cannot be used",
                    ));
                }
                offered = true;
                Cred::userpass_plaintext(&credentials.username, credentials.token.expose())
            });
        }
        callbacks
    }

    /// Read the head of `reference` on `remote` right now.
    fn remote_head(
        &self,
        remote: &mut Remote<'_>,
        reference: &str,
    ) -> Result<Option<Oid>, GitError> {
        let list_error = |source| GitError::List {
            remote: ORIGIN.to_owned(),
            source,
        };
        let connection = remote
            .connect_auth(Direction::Push, Some(self.callbacks()), Some(Self::proxy()))
            .map_err(list_error)?;
        let heads = connection.list().map_err(list_error)?;
        Ok(heads
            .iter()
            .find(|head| head.name() == reference)
            .map(RemoteHead::oid))
    }

    /// Push `refspec` to `remote`, failing when the remote rejects an update.
    fn push(
        &self,
        remote: &mut Remote<'_>,
        refspec: &str,
        reference: &str,
    ) -> Result<(), GitError> {
        let rejection = RefCell::new(None);
        let mut callbacks = self.callbacks();
        callbacks.push_update_reference(|name, status| {
            if let Some(status) = status {
                rejection
                    .borrow_mut()
                    .get_or_insert_with(|| (name.to_owned(), status.to_owned()));
            }
            Ok(())
        });
        let mut options = PushOptions::new();
        options
            .remote_callbacks(callbacks)
            .proxy_options(Self::proxy());
        remote
            .push(&[refspec], Some(&mut options))
            .map_err(|source| GitError::Push {
                reference: reference.to_owned(),
                source,
            })?;
        drop(options);
        match rejection.into_inner() {
            Some((rejected, status)) => Err(GitError::Rejected {
                reference: rejected,
                status,
            }),
            None => Ok(()),
        }
    }
}

impl GitCommands for SystemGit {
    type Error = GitError;

    fn authoritative_head(&self, repository: &Path, branch: &str) -> Result<String, Self::Error> {
        self.resolve(repository, branch)
    }

    fn create_tag(
        &self,
        repository: &Path,
        tag: &str,
        commit: &str,
        author: Author<'_>,
    ) -> Result<(), Self::Error> {
        let repo = Self::open(repository)?;
        let tag_error = |source| GitError::Tag {
            tag: tag.to_owned(),
            source,
        };
        let target = Self::commit(&repo, commit).map_err(tag_error)?;
        let tagger = Signature::now(author.name, author.email).map_err(tag_error)?;
        let message = message_prettify(tag, None).map_err(tag_error)?;
        repo.tag(tag, target.as_object(), &tagger, &message, false)
            .map_err(tag_error)
            .map(drop)
    }

    fn push_tag(&self, repository: &Path, tag: &str) -> Result<(), Self::Error> {
        let repo = Self::open(repository)?;
        let mut remote = Self::origin(&repo)?;
        let reference = format!("refs/tags/{tag}");
        self.push(&mut remote, &format!("{reference}:{reference}"), &reference)
    }
}

impl GitRefs for SystemGit {
    type Error = GitError;

    fn reference(&self, repository: &Path, name: &str) -> Result<Option<String>, Self::Error> {
        let repo = Self::open(repository)?;
        let reference_error = |source| GitError::Reference {
            name: name.to_owned(),
            source,
        };
        let reference = match repo.find_reference(name) {
            Ok(reference) => reference,
            Err(error) if error.code() == ErrorCode::NotFound => return Ok(None),
            Err(error) => return Err(reference_error(error)),
        };
        let commit = reference.peel_to_commit().map_err(reference_error)?;
        Ok(Some(commit.id().to_string()))
    }
}

impl GitHistory for SystemGit {
    type Error = GitError;

    fn tags(&self, repository: &Path, prefix: &str) -> Result<Vec<String>, Self::Error> {
        let names = Self::open(repository)?
            .tag_names(None)
            .map_err(GitError::Tags)?;
        Ok(names
            .iter_bytes()
            .filter_map(|name| str::from_utf8(name).ok())
            .filter(|name| name.starts_with(prefix))
            .map(str::to_owned)
            .collect())
    }

    fn resolve(&self, repository: &Path, rev: &str) -> Result<String, Self::Error> {
        let repo = Self::open(repository)?;
        let commit = Self::commit(&repo, rev).map_err(|source| GitError::Resolve {
            revision: rev.to_owned(),
            source,
        })?;
        Ok(commit.id().to_string())
    }

    fn has_changes(
        &self,
        repository: &Path,
        from: Option<&str>,
        to: &str,
        scope: UnitScope<'_>,
    ) -> Result<bool, Self::Error> {
        let repo = Self::open(repository)?;
        let diff_error = |source| GitError::Diff {
            from: from.map(str::to_owned),
            to: to.to_owned(),
            paths: scope.paths(),
            source,
        };
        let tree = |rev: &str| {
            repo.revparse_single(rev)
                .and_then(|object| object.peel_to_tree())
                .map_err(diff_error)
        };
        let old = from.map(tree).transpose()?;
        let new = tree(to)?;
        scope.differs(&repo, old.as_ref(), &new).map_err(diff_error)
    }

    fn commit_messages(
        &self,
        repository: &Path,
        from: Option<&str>,
        to: &str,
        scope: UnitScope<'_>,
    ) -> Result<Vec<String>, Self::Error> {
        let repo = Self::open(repository)?;
        let history_error = |source| GitError::History {
            from: from.map(str::to_owned),
            to: to.to_owned(),
            paths: scope.paths(),
            source,
        };
        let commit_id = |rev: &str| Self::commit(&repo, rev).map(|commit| commit.id());
        let mut walk = repo.revwalk().map_err(history_error)?;
        walk.set_sorting(Sort::TOPOLOGICAL | Sort::REVERSE)
            .and_then(|()| walk.push(commit_id(to)?))
            .and_then(|()| from.map_or(Ok(()), |from| walk.hide(commit_id(from)?)))
            .map_err(history_error)?;
        let mut messages = Vec::new();
        for id in walk {
            let commit = id
                .and_then(|id| repo.find_commit(id))
                .map_err(history_error)?;
            if commit.parent_count() > 1 {
                continue;
            }
            let parent = match commit.parent(0) {
                Ok(parent) => Some(parent.tree().map_err(history_error)?),
                Err(error) if error.code() == ErrorCode::NotFound => None,
                Err(error) => return Err(history_error(error)),
            };
            let tree = commit.tree().map_err(history_error)?;
            if scope
                .differs(&repo, parent.as_ref(), &tree)
                .map_err(history_error)?
            {
                messages.push(String::from_utf8_lossy(commit.message_bytes()).into_owned());
            }
        }
        Ok(messages)
    }

    fn is_ancestor(
        &self,
        repository: &Path,
        ancestor: &str,
        descendant: &str,
    ) -> Result<bool, Self::Error> {
        let repo = Self::open(repository)?;
        let commit = |revision: &str| {
            Self::commit(&repo, revision)
                .map(|commit| commit.id())
                .map_err(|source| GitError::Resolve {
                    revision: revision.to_owned(),
                    source,
                })
        };
        let (ancestor_id, descendant_id) = (commit(ancestor)?, commit(descendant)?);
        if ancestor_id == descendant_id {
            return Ok(true);
        }
        repo.graph_descendant_of(descendant_id, ancestor_id)
            .map_err(|source| GitError::Ancestry {
                ancestor: ancestor.to_owned(),
                descendant: descendant.to_owned(),
                source,
            })
    }

    fn equivalent(
        &self,
        repository: &Path,
        base: &str,
        first: &str,
        second: &str,
    ) -> Result<bool, Self::Error> {
        type Chain = Vec<(Oid, Vec<u8>)>;
        let repo = Self::open(repository)?;
        let commit = |revision: &str| {
            Self::commit(&repo, revision).map_err(|source| GitError::Resolve {
                revision: revision.to_owned(),
                source,
            })
        };
        let base = commit(base)?.id();
        let chain = |head: &str| -> Result<Option<Chain>, GitError> {
            let mut current = commit(head)?;
            let mut chain = Vec::new();
            while current.id() != base {
                chain.push((current.tree_id(), current.message_bytes().to_vec()));
                let Some(parent) = current.parent_ids().next() else {
                    return Ok(None);
                };
                current = commit(&parent.to_string())?;
            }
            Ok(Some(chain))
        };
        let (first, second) = (chain(first)?, chain(second)?);
        Ok(first.is_some() && first == second)
    }
}

impl ProposalGit for SystemGit {
    type Error = GitError;

    fn fetch_if_present(&self, repository: &Path, refspec: &str) -> Result<(), Self::Error> {
        match self.fetch(repository, refspec) {
            Err(GitError::Fetch {
                source,
                remote: _,
                refspec: _,
            }) if source.code() == ErrorCode::NotFound => Ok(()),
            result => result,
        }
    }

    fn fetch(&self, repository: &Path, refspec: &str) -> Result<(), Self::Error> {
        let repo = Self::open(repository)?;
        let mut origin = Self::origin(&repo)?;
        let mut options = FetchOptions::new();
        options
            .remote_callbacks(self.callbacks())
            .proxy_options(Self::proxy());
        origin
            .fetch(&[refspec], Some(&mut options), None)
            .map_err(|source| GitError::Fetch {
                remote: ORIGIN.to_owned(),
                refspec: refspec.to_owned(),
                source,
            })
    }

    fn worktree_add(
        &self,
        repository: &Path,
        path: &Path,
        baseline: &str,
    ) -> Result<(), Self::Error> {
        let repo = Self::open(repository)?;
        let add_error = |source| GitError::WorktreeAdd {
            path: path.to_path_buf(),
            source,
        };
        let commit = Self::commit(&repo, baseline).map_err(add_error)?;
        let name = Self::worktree_name(path);
        let mut branch = repo.branch(&name, &commit, true).map_err(add_error)?;
        let mut options = WorktreeAddOptions::new();
        options.reference(Some(branch.get()));
        let result = repo.worktree(&name, path, Some(&options));
        if let Err(source) = result {
            drop(branch.delete());
            return Err(add_error(source));
        }
        Ok(())
    }

    fn worktree_remove(&self, repository: &Path, path: &Path) -> Result<(), Self::Error> {
        let repo = Self::open(repository)?;
        let remove_error = |source| GitError::WorktreeRemove {
            path: path.to_path_buf(),
            source,
        };
        let name = Self::worktree_name(path);
        let worktree = repo.find_worktree(&name).map_err(remove_error)?;
        let prune = worktree.prune(Some(
            WorktreePruneOptions::new()
                .valid(true)
                .locked(true)
                .working_tree(true),
        ));
        let branch = repo
            .find_branch(&name, BranchType::Local)
            .and_then(|mut branch| branch.delete());
        match (prune, branch) {
            (Ok(()), Ok(())) => Ok(()),
            (Err(prune), Err(branch)) => Err(GitError::WorktreeRemoveFailed {
                path: path.to_path_buf(),
                prune,
                branch,
            }),
            (Err(source), Ok(())) | (Ok(()), Err(source)) => Err(remove_error(source)),
        }
    }

    fn stage_update(&self, worktree: &Path, paths: &[PathBuf]) -> Result<(), Self::Error> {
        let repo = Self::open(worktree)?;
        let stage_error = |source| GitError::Stage {
            worktree: worktree.to_path_buf(),
            source,
        };
        let mut index = repo.index().map_err(stage_error)?;
        for path in paths {
            if worktree.join(path).symlink_metadata().is_ok() {
                index.add_path(path).map_err(stage_error)?;
            } else {
                index.remove_path(path).map_err(stage_error)?;
            }
        }
        index.write().map_err(stage_error)
    }

    fn commit_if_staged(
        &self,
        worktree: &Path,
        message: &str,
        author: Author<'_>,
    ) -> Result<Option<String>, Self::Error> {
        let repo = Self::open(worktree)?;
        let commit_error = |source| GitError::Commit {
            worktree: worktree.to_path_buf(),
            source,
        };
        let tree = repo
            .index()
            .and_then(|mut index| index.write_tree())
            .and_then(|id| repo.find_tree(id))
            .map_err(commit_error)?;
        let parent = match repo.head() {
            Ok(head) => Some(head.peel_to_commit().map_err(commit_error)?),
            Err(error) if error.code() == ErrorCode::UnbornBranch => None,
            Err(error) => return Err(commit_error(error)),
        };
        let unchanged = parent
            .as_ref()
            .map_or_else(|| tree.is_empty(), |parent| parent.tree_id() == tree.id());
        if unchanged {
            return Ok(None);
        }
        let signature = Signature::now(author.name, author.email).map_err(commit_error)?;
        let message = message_prettify(message, None).map_err(commit_error)?;
        let parents: Vec<_> = parent.iter().collect();
        let commit = repo
            .commit(
                Some("HEAD"),
                &signature,
                &signature,
                &message,
                &tree,
                &parents,
            )
            .map_err(commit_error)?;
        Ok(Some(commit.to_string()))
    }

    /// Emulates `--force-with-lease` by reading the remote branch head
    /// immediately before a forced push; a concurrent update between the
    /// read and the push can still be overwritten.
    fn push_with_lease(
        &self,
        worktree: &Path,
        branch: &str,
        expected: Option<&str>,
    ) -> Result<(), Self::Error> {
        let repo = Self::open(worktree)?;
        let mut remote = Self::origin(&repo)?;
        let reference = format!("refs/heads/{branch}");
        let actual = self
            .remote_head(&mut remote, &reference)?
            .map(|head| head.to_string());
        if actual.as_deref() != expected {
            return Err(GitError::StaleLease {
                reference,
                expected: expected.map(str::to_owned),
                actual,
            });
        }
        self.push(&mut remote, &format!("+HEAD:{reference}"), &reference)
    }
}

#[cfg(test)]
mod tests {
    use std::fs;
    use std::path::Path;

    use ephemeris_files::RepositoryPath;
    use ephemeris_token::Token;
    use git2::build::RepoBuilder;
    use git2::{IndexAddOption, Repository, RepositoryInitOptions, Signature};

    use super::{
        GitError, GitHistory as _, ProposalGit as _, RemoteCredentials, SystemGit, UnitScope,
    };
    use crate::{Author, GitCommands as _, GitRefs as _};

    const AUTHOR: Author<'static> = Author {
        name: "Release Bot",
        email: "release@example.invalid",
    };

    /// A repository without any user configuration.
    struct Repo(Repository);

    impl Repo {
        /// Initialize a repository on `main` at `path`.
        fn init(path: &Path) -> Self {
            let repository =
                Repository::init_opts(path, RepositoryInitOptions::new().initial_head("main"))
                    .unwrap();
            Self(repository)
        }

        /// Initialize a bare repository at `path`.
        fn bare(path: &Path) -> Self {
            Self(Repository::init_bare(path).unwrap())
        }

        /// Clone `branch` of the repository at `remote` into `path`.
        fn clone_branch(remote: &Path, branch: &str, path: &Path) -> Self {
            let repository = RepoBuilder::new()
                .branch(branch)
                .clone(remote.to_str().unwrap(), path)
                .unwrap();
            Self(repository)
        }

        /// Stage `paths` as `git add` does, including deletions.
        fn add(&self, paths: &[&str]) {
            let mut index = self.0.index().unwrap();
            index.add_all(paths, IndexAddOption::DEFAULT, None).unwrap();
            index.update_all(paths, None).unwrap();
            index.write().unwrap();
        }

        /// Stage every change, as `git add --all` does, and commit it.
        fn commit_all(&self, message: &str) -> String {
            self.add(&["*"]);
            self.commit(message)
        }

        /// Commit the index on `HEAD`.
        fn commit(&self, message: &str) -> String {
            let tree = self
                .0
                .find_tree(self.0.index().unwrap().write_tree().unwrap())
                .unwrap();
            let signature = Signature::now("Release test", "release-test@example.invalid").unwrap();
            let parent = self
                .0
                .head()
                .ok()
                .map(|head| head.peel_to_commit().unwrap());
            let parents: Vec<_> = parent.iter().collect();
            self.0
                .commit(
                    Some("HEAD"),
                    &signature,
                    &signature,
                    message,
                    &tree,
                    &parents,
                )
                .unwrap()
                .to_string()
        }

        /// Create a lightweight tag on `HEAD`.
        fn tag(&self, name: &str) {
            let head = self.0.revparse_single("HEAD").unwrap();
            self.0.tag_lightweight(name, &head, false).unwrap();
        }

        /// Add the repository at `url` as `origin`.
        fn add_origin(&self, url: &Path) {
            self.0.remote("origin", url.to_str().unwrap()).unwrap();
        }

        /// Push `refspec` to `origin`.
        fn push(&self, refspec: &str) {
            self.0
                .find_remote("origin")
                .unwrap()
                .push(&[refspec], None)
                .unwrap();
        }

        /// The commit `revision` names.
        fn resolve(&self, revision: &str) -> String {
            self.0
                .revparse_single(revision)
                .unwrap()
                .peel_to_commit()
                .unwrap()
                .id()
                .to_string()
        }

        /// The commit a full reference name points at, if it exists.
        fn reference(&self, name: &str) -> Option<String> {
            self.0
                .find_reference(name)
                .ok()
                .map(|reference| reference.peel_to_commit().unwrap().id().to_string())
        }
    }

    fn fixture() -> (tempfile::TempDir, Repo) {
        let root = tempfile::tempdir().unwrap();
        let repository = Repo::init(root.path());
        fs::write(root.path().join("README.md"), "fixture\n").unwrap();
        repository.commit_all("Initial");
        (root, repository)
    }

    fn directories(paths: &[&str]) -> Vec<RepositoryPath> {
        paths.iter().map(|path| path.parse().unwrap()).collect()
    }

    fn scope(source: &[RepositoryPath]) -> UnitScope<'_> {
        UnitScope {
            source,
            changelog: Some(Path::new("app/CHANGELOG.md")),
        }
    }

    #[test]
    fn tags_lists_only_matching_names_by_prefix() {
        let (root, repository) = fixture();
        repository.tag("app-v1.0.0");
        repository.tag("app-v1.1.0");
        repository.tag("lib-v1.0.0");
        let mut tags = SystemGit::default().tags(root.path(), "app-v").unwrap();
        tags.sort();
        assert_eq!(tags, ["app-v1.0.0", "app-v1.1.0"]);
    }

    #[test]
    fn credentials_keep_the_username_and_redact_the_token() {
        let credentials = RemoteCredentials::new("oauth2", Token::new("secret"));
        assert_eq!(credentials.username, "oauth2");
        assert!(!format!("{credentials:?}").contains("secret"));
    }

    #[test]
    fn has_changes_limits_the_comparison_to_a_directory() {
        let (root, repository) = fixture();
        let git_adapter = SystemGit::default();
        let before = git_adapter.resolve(root.path(), "HEAD").unwrap();
        fs::create_dir_all(root.path().join("app/src")).unwrap();
        fs::write(root.path().join("app/src/main.txt"), "changed\n").unwrap();
        repository.commit_all("Change app");
        for (path, changed) in [
            ("app", true),
            ("app/src", true),
            ("lib", false),
            (".", true),
        ] {
            assert_eq!(
                git_adapter
                    .has_changes(
                        root.path(),
                        Some(&before),
                        "HEAD",
                        scope(&directories(&[path]))
                    )
                    .unwrap(),
                changed,
                "{path:?}"
            );
        }
    }

    #[test]
    fn commit_messages_list_the_commits_that_change_a_directory_oldest_first() {
        let (root, repository) = fixture();
        let git_adapter = SystemGit::default();
        repository.tag("app-v1.0.0");
        fs::create_dir_all(root.path().join("app")).unwrap();
        for (path, message) in [
            ("app/a.txt", "feat: first"),
            ("lib.txt", "fix: elsewhere"),
            ("app/b.txt", "fix: second\n\nBody."),
        ] {
            fs::write(root.path().join(path), message).unwrap();
            repository.commit_all(message);
        }
        let messages = |path: &str| {
            git_adapter
                .commit_messages(
                    root.path(),
                    Some("app-v1.0.0"),
                    "HEAD",
                    scope(&directories(&[path])),
                )
                .unwrap()
        };
        assert_eq!(messages("app"), ["feat: first", "fix: second\n\nBody."]);
        assert_eq!(messages(".").len(), 3);
        assert_eq!(messages("other"), Vec::<String>::new());
    }

    #[test]
    fn without_a_baseline_the_walk_reaches_the_root_commit() {
        let (root, repository) = fixture();
        let git_adapter = SystemGit::default();
        fs::create_dir_all(root.path().join("app")).unwrap();
        fs::write(root.path().join("app/a.txt"), "a\n").unwrap();
        repository.commit_all("feat: first");
        let messages = |path: &str| {
            git_adapter
                .commit_messages(root.path(), None, "HEAD", scope(&directories(&[path])))
                .unwrap()
        };
        assert_eq!(messages("."), ["Initial", "feat: first"]);
        assert_eq!(messages("app"), ["feat: first"]);
        assert_eq!(messages("lib"), Vec::<String>::new());
        let changed = |path: &str| {
            git_adapter
                .has_changes(root.path(), None, "HEAD", scope(&directories(&[path])))
                .unwrap()
        };
        assert!(changed("app"));
        assert!(!changed("lib"));
    }

    #[test]
    fn a_scope_with_several_directories_counts_a_change_in_any_of_them() {
        let (root, repository) = fixture();
        let git_adapter = SystemGit::default();
        let before = git_adapter.resolve(root.path(), "HEAD").unwrap();
        fs::create_dir_all(root.path().join("shared")).unwrap();
        fs::write(root.path().join("shared/a.txt"), "changed\n").unwrap();
        repository.commit_all("Change shared");
        for (paths, changed) in [
            (&["app", "shared"][..], true),
            (&["app", "lib"][..], false),
            (&["app", "."][..], true),
        ] {
            assert_eq!(
                git_adapter
                    .has_changes(
                        root.path(),
                        Some(&before),
                        "HEAD",
                        scope(&directories(paths))
                    )
                    .unwrap(),
                changed,
                "{paths:?}"
            );
        }
    }

    #[test]
    fn the_unit_changelog_is_neither_a_change_nor_a_listed_commit() {
        let (root, repository) = fixture();
        let git_adapter = SystemGit::default();
        repository.tag("app-v1.0.0");
        fs::create_dir_all(root.path().join("app")).unwrap();
        fs::write(root.path().join("app/CHANGELOG.md"), "notes\n").unwrap();
        repository.commit_all("docs: changelog only");
        let only_changelog = repository.resolve("HEAD");
        let changes = |to: &str| {
            git_adapter
                .has_changes(
                    root.path(),
                    Some("app-v1.0.0"),
                    to,
                    scope(&directories(&["app"])),
                )
                .unwrap()
        };
        let messages = || {
            git_adapter
                .commit_messages(
                    root.path(),
                    Some("app-v1.0.0"),
                    "HEAD",
                    scope(&directories(&["app"])),
                )
                .unwrap()
        };
        assert!(!changes(&only_changelog));
        assert_eq!(messages(), Vec::<String>::new());
        fs::write(root.path().join("app/main.txt"), "code\n").unwrap();
        fs::write(root.path().join("app/CHANGELOG.md"), "more notes\n").unwrap();
        repository.commit_all("feat: code and changelog");
        assert!(changes("HEAD"));
        assert_eq!(messages(), ["feat: code and changelog"]);
    }

    #[test]
    fn without_a_changelog_every_file_in_the_source_counts() {
        let (root, repository) = fixture();
        let git_adapter = SystemGit::default();
        repository.tag("app-v1.0.0");
        fs::create_dir_all(root.path().join("app")).unwrap();
        fs::write(root.path().join("app/CHANGELOG.md"), "notes\n").unwrap();
        repository.commit_all("docs: changelog only");
        let source = directories(&["app"]);
        let scope = UnitScope {
            source: &source,
            changelog: None,
        };
        assert!(
            git_adapter
                .has_changes(root.path(), Some("app-v1.0.0"), "HEAD", scope)
                .unwrap()
        );
    }

    #[test]
    fn a_tag_is_signed_by_the_given_author_without_user_configuration() {
        let (root, repository) = fixture();
        let head = repository.resolve("HEAD");
        SystemGit::default()
            .create_tag(root.path(), "app-v1.0.0", &head, AUTHOR)
            .unwrap();
        let repo = Repository::open(root.path()).unwrap();
        let tag = repo
            .find_reference("refs/tags/app-v1.0.0")
            .unwrap()
            .peel_to_tag()
            .unwrap();
        assert_eq!(tag.tagger().unwrap().name().unwrap(), "Release Bot");
    }

    #[test]
    fn a_commit_is_an_ancestor_of_itself_and_of_its_descendants_only() {
        let (root, repository) = fixture();
        let first = repository.resolve("HEAD");
        fs::write(root.path().join("README.md"), "changed\n").unwrap();
        let second = repository.commit_all("Second");
        let adapter = SystemGit::default();
        assert!(adapter.is_ancestor(root.path(), &first, &second).unwrap());
        assert!(adapter.is_ancestor(root.path(), &second, &second).unwrap());
        assert!(!adapter.is_ancestor(root.path(), &second, &first).unwrap());
    }

    #[test]
    fn resolve_and_reference_name_commits_and_peel_annotated_tags() {
        let (root, repository) = fixture();
        let git_adapter = SystemGit::default();
        let head = repository.resolve("HEAD");
        assert_eq!(git_adapter.resolve(root.path(), "HEAD").unwrap(), head);
        git_adapter
            .create_tag(root.path(), "app-v1.0.0", &head, AUTHOR)
            .unwrap();
        assert_eq!(
            git_adapter.resolve(root.path(), "app-v1.0.0").unwrap(),
            head
        );
        assert_eq!(
            git_adapter
                .reference(root.path(), "refs/tags/app-v1.0.0")
                .unwrap(),
            Some(head)
        );
        assert_eq!(
            git_adapter
                .reference(root.path(), "refs/tags/missing")
                .unwrap(),
            None
        );
    }

    #[test]
    fn fetch_if_present_reports_an_unreachable_remote() {
        let git_adapter = SystemGit::default();
        let remote = tempfile::tempdir().unwrap();
        Repo::bare(remote.path());
        let (root, repository) = fixture();
        repository.add_origin(remote.path());
        repository.push("refs/heads/main:refs/heads/main");
        let spec = |branch: &str| format!("+refs/heads/{branch}:refs/remotes/origin/{branch}");
        for branch in ["main", "proposal"] {
            git_adapter
                .fetch_if_present(root.path(), &spec(branch))
                .unwrap();
        }
        fs::remove_dir_all(remote.path()).unwrap();
        assert!(matches!(
            git_adapter.fetch_if_present(root.path(), &spec("main")),
            Err(GitError::Fetch {
                remote: _,
                refspec: _,
                source: _
            })
        ));
    }

    #[test]
    fn worktree_lifecycle_and_lease_push_round_trip() {
        let git_adapter = SystemGit::default();
        let remote = tempfile::tempdir().unwrap();
        Repo::bare(remote.path());
        let (root, repository) = fixture();
        repository.add_origin(remote.path());
        repository.push("refs/heads/main:refs/heads/main");

        let worktree_dir = tempfile::tempdir().unwrap();
        let worktree_path = worktree_dir.path().join("wt");
        let head = git_adapter.resolve(root.path(), "HEAD").unwrap();
        git_adapter
            .worktree_add(root.path(), &worktree_path, &head)
            .unwrap();
        fs::write(worktree_path.join("generated.txt"), "content\n").unwrap();
        git_adapter
            .stage_update(&worktree_path, &["generated.txt".into()])
            .unwrap();
        let commit = git_adapter
            .commit_if_staged(&worktree_path, "release: update proposal", AUTHOR)
            .unwrap();
        assert!(commit.is_some());
        let worktree_repo = Repository::open(&worktree_path).unwrap();
        let committed = worktree_repo.head().unwrap().peel_to_commit().unwrap();
        assert_eq!(committed.author().name().unwrap(), "Release Bot");
        assert_eq!(
            committed.committer().email().unwrap(),
            "release@example.invalid"
        );
        assert!(
            git_adapter
                .commit_if_staged(&worktree_path, "release: update proposal", AUTHOR)
                .unwrap()
                .is_none()
        );
        git_adapter
            .push_with_lease(&worktree_path, "proposal", None)
            .unwrap();
        assert!(matches!(
            git_adapter.push_with_lease(&worktree_path, "proposal", None),
            Err(GitError::StaleLease {
                reference: _,
                expected: None,
                actual: Some(actual),
            }) if Some(actual.as_str()) == commit.as_deref()
        ));
        git_adapter
            .worktree_remove(root.path(), &worktree_path)
            .unwrap();
        assert!(!worktree_path.exists());

        let clone = tempfile::tempdir().unwrap();
        Repo::clone_branch(remote.path(), "proposal", clone.path());
        assert_eq!(
            fs::read_to_string(clone.path().join("generated.txt")).unwrap(),
            "content\n"
        );
    }

    #[test]
    fn worktree_remove_deletes_the_branch_even_when_pruning_fails() {
        use std::os::unix::fs::PermissionsExt as _;

        let git_adapter = SystemGit::default();
        let (root, _repository) = fixture();
        let head = git_adapter.resolve(root.path(), "HEAD").unwrap();
        let worktree_dir = tempfile::tempdir().unwrap();
        let worktree_path = worktree_dir.path().join("wt");
        git_adapter
            .worktree_add(root.path(), &worktree_path, &head)
            .unwrap();
        let name = SystemGit::worktree_name(&worktree_path);

        // Denying write access to the administrative worktrees directory
        // makes libgit2 fail to remove the worktree's metadata directory,
        // without preventing the branch lookup and deletion that follows.
        let admin_parent = root.path().join(".git/worktrees");
        fs::set_permissions(&admin_parent, fs::Permissions::from_mode(0o555)).unwrap();
        let result = git_adapter.worktree_remove(root.path(), &worktree_path);
        fs::set_permissions(&admin_parent, fs::Permissions::from_mode(0o755)).unwrap();

        assert!(matches!(
            result,
            Err(GitError::WorktreeRemove { path: _, source: _ })
        ));
        assert_eq!(
            git_adapter
                .reference(root.path(), &format!("refs/heads/{name}"))
                .unwrap(),
            None
        );
    }

    #[test]
    fn worktree_add_removes_the_branch_when_the_worktree_already_exists() {
        let git_adapter = SystemGit::default();
        let (root, _repository) = fixture();
        let head = git_adapter.resolve(root.path(), "HEAD").unwrap();
        let worktree_dir = tempfile::tempdir().unwrap();
        let worktree_path = worktree_dir.path().join("wt");
        fs::create_dir_all(&worktree_path).unwrap();
        fs::write(worktree_path.join("occupied.txt"), "occupied\n").unwrap();

        let error = git_adapter
            .worktree_add(root.path(), &worktree_path, &head)
            .unwrap_err();
        assert!(matches!(
            error,
            GitError::WorktreeAdd { path: _, source: _ }
        ));
        let branch = SystemGit::worktree_name(&worktree_path);
        assert_eq!(
            git_adapter
                .reference(root.path(), &format!("refs/heads/{branch}"))
                .unwrap(),
            None
        );
    }

    #[test]
    fn pushed_tags_reach_the_remote() {
        let git_adapter = SystemGit::default();
        let remote_dir = tempfile::tempdir().unwrap();
        let remote = Repo::bare(remote_dir.path());
        let (root, repository) = fixture();
        repository.add_origin(remote_dir.path());
        let head = repository.resolve("HEAD");
        git_adapter
            .create_tag(root.path(), "app-v1.0.0", &head, AUTHOR)
            .unwrap();
        git_adapter.push_tag(root.path(), "app-v1.0.0").unwrap();
        assert_eq!(remote.reference("refs/tags/app-v1.0.0"), Some(head));
    }
}