astrid-runtime/astrid · error

--git-history requires NAME=REPO::RELATIVE_PATH

Error message

--git-history requires NAME=REPO::RELATIVE_PATH

What it means

Format error in `parse_git_specification`: the `--git-history` value, after the mandatory `NAME=PATH` split, has no `::` separator. The value must be `NAME=REPO::RELATIVE_PATH`; the parser needs both the repository path and the in-repo relative path to walk git history, and refuses an ambiguous or malformed spec.

Source

Thrown at crates/astrid-storage-chunker-evidence/src/main.rs:207

    targets_kib.sort_unstable();
    targets_kib.dedup();
    Ok(Options {
        corpus_specs,
        version_chain_specs,
        git_history_specs,
        include_synthetic,
        sketch_only,
        targets_kib,
        output,
    })
}

fn parse_git_specification(specification: Option<String>) -> Result<(String, PathBuf, PathBuf)> {
    let (name, combined) = parse_path_specification("--git-history", specification)?;
    let combined = combined.to_string_lossy();
    let (repository, relative_path) = combined
        .split_once("::")
        .ok_or_else(|| anyhow::anyhow!("--git-history requires NAME=REPO::RELATIVE_PATH"))?;
    if repository.is_empty() || relative_path.is_empty() {
        bail!("--git-history requires non-empty NAME=REPO::RELATIVE_PATH");
    }
    Ok((
        name,
        PathBuf::from(repository),
        PathBuf::from(relative_path),
    ))
}

fn parse_path_specification(
    flag: &str,
    specification: Option<String>,
) -> Result<(String, PathBuf)> {
    let specification =
        specification.ok_or_else(|| anyhow::anyhow!("{flag} requires NAME=PATH"))?;
    let (name, path) = specification
        .split_once('=')

View on GitHub (pinned to affd8760f4)

Solutions

1. Format the value as `NAME=REPO::RELATIVE_PATH`, e.g. `--git-history kernel=/src/repo::crates/kernel`.
2. Quote the argument in the shell so `::` is preserved.
3. Cross-check the syntax in `--help` output (`--git-history NAME=REPO::RELATIVE_PATH`).

Example fix

// before
mybin --git-history kernel=/src/repo
// after
mybin --git-history 'kernel=/src/repo::crates/kernel'

fn valid_git_spec(spec: &str) -> bool {
    let (_n, rest) = spec.split_once('=').unwrap_or(("", ""));
    match rest.split_once("::") {
        Some((repo, rel)) => !repo.is_empty() && !rel.is_empty(),
        None => false,
    }
}

let spec = "kernel=/src/repo::crates/kernel";
assert!(valid_git_spec(spec), "--git-history requires NAME=REPO::RELATIVE_PATH");

When it happens

Trigger: Passing `--git-history NAME=/path/to/repo` (single `=`, no `::`), or forgetting the `::RELATIVE_PATH` part entirely. (An empty repo or relative path segment raises the sibling 'non-empty' bail at main.rs:209.)

Common situations: Confusing `--git-history` syntax with `--corpus`/`--version-chain` (which only need `NAME=PATH`); shell quoting stripping or mangling the `::`; copying an example without the relative path.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• git could not inspect captured version: {}
• unknown argument {unknown:?}; use --help
• --git-history requires non-empty NAME=REPO::RELATIVE_PATH
• --var must be KEY=VALUE (got {item:?})
• --target-kib requires an integer

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/54ed7b7baa0ad349. Report an issue: GitHub.