GitoxideLabs/gitoxide · error · anyhow::Error

specify at least one contact to run through the mailmap

Error message

specify at least one contact to run through the mailmap

What it means

`gix mailmap check` requires at least one contact to run through the mailmap. When the `contacts` list is empty the command bails with this instruction instead of producing empty output. It is an argument-validation guard.

Solutions

1. Pass at least one contact, e.g. `gix mailmap check "Name <email@example.com>"`
2. Fix the upstream script/filter that produced an empty contact list
3. Verify quoting so contacts are not swallowed by the shell

Example fix

// before
$ gix mailmap check
// after
$ gix mailmap check "Jane Doe <jane@example.com>"

if contacts.is_empty() {
    eprintln!("mailmap check needs at least one contact");
    std::process::exit(2);
}

When it happens

Trigger: Invoking `gix mailmap check` with no contact arguments, so the `contacts: Vec<BString>` is empty and the `contacts.is_empty()` check fires.

Common situations: Running the subcommand with only flags and no positional contact; a script that builds the contact list from a filter that matched nothing; forgetting that contacts are required arguments, not read from stdin.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Invalid pathspec - path must not be empty, not be excluded…
• path does not name a file
• exactly one time-travel destination is required
• expected exactly one hexadecimal commit ID
• ' ' is not a valid configuration key

AI-assisted analysis of GitoxideLabs/gitoxide@e73179060b (2026-09-08). Data as JSON: /api/errors/117ede143596ca7d. Report an issue: GitHub.

Appendix: source

Thrown at gitoxide-core/src/repository/mailmap.rs:64

    #[cfg(feature = "serde")]
    serde_json::to_writer_pretty(out, &mailmap.iter().map(JsonEntry::from).collect::<Vec<_>>())?;

    Ok(())
}

pub fn check(
    repo: gix::Repository,
    format: OutputFormat,
    contacts: Vec<BString>,
    mut out: impl io::Write,
    mut err: impl io::Write,
) -> anyhow::Result<()> {
    if format != OutputFormat::Human {
        bail!("Only human output is supported right now");
    }
    if contacts.is_empty() {
        bail!("specify at least one contact to run through the mailmap")
    }

    let mut mailmap = gix::mailmap::Snapshot::default();
    if let Err(err) = repo.open_mailmap_into(&mut mailmap) {
        bail!(err);
    }

    let mut buf = Vec::new();
    for contact in contacts {
        let actor = match gix::actor::IdentityRef::from_bytes(&contact) {
            Ok(a) => a,
            Err(_) => {
                let Some(email) = contact
                    .trim_start()
                    .strip_prefix(b"<")
                    .and_then(|rest| rest.trim_end().strip_suffix(b">"))
                else {
                    writeln!(err, "Failed to parse contact '{contact}' - skipping")?;

View on GitHub (pinned to e73179060b)