jdx/mise · error

brew-cask:{}: git only_path must stay within the checkout

Error message

brew-cask:{}: git only_path must stay within the checkout

What it means

When a cask's URL is a git repository, an optional `only_path` selects a subdirectory of the clone to stage. Before use, mise rejects any only_path that is absolute or contains a parent-dir ('..') or Windows prefix component, because such a path could escape the checkout directory. This is a path-traversal guard, so the fetch fails fast rather than copying files from outside the clone.

Source

Thrown at src/system/packages/brew/cask/fetch.rs:213

            let dest = extract_dir.join(entry.file_name());
            file::rename(entry.path(), &dest)?;
        }
    }
    file::remove_all(&clone_dir)?;
    Ok(extract_dir)
}

pub(super) fn git_only_path_source(
    cask: &Cask,
    clone_dir: &Path,
    only_path: &Path,
) -> Result<PathBuf> {
    if only_path.is_absolute()
        || only_path
            .components()
            .any(|component| matches!(component, Component::ParentDir | Component::Prefix(_)))
    {
        bail!(
            "brew-cask:{}: git only_path must stay within the checkout",
            cask.token
        );
    }
    let clone_root = clone_dir.canonicalize()?;
    let source = clone_dir.join(only_path).canonicalize().wrap_err_with(|| {
        format!(
            "brew-cask:{}: git only_path does not exist: {}",
            cask.token,
            only_path.display()
        )
    })?;
    if !source.starts_with(&clone_root) || !source.is_dir() {
        bail!(
            "brew-cask:{}: git only_path must name a directory within the checkout",
            cask.token
        );
    }

View on GitHub (pinned to afd2eddd3a)

Solutions

1. Edit the cask's only_path to a relative path with no '..' segments (e.g. 'src/app' instead of '/build/src/app' or '../app').
2. If the desired directory is outside the repository, point the cask URL at the repository that actually contains it.
3. Clear the cask metadata cache and retry after fixing the cask definition.

Example fix

// before (cask url_specs)
"only_path": "/build/output/App"
// after
"only_path": "build/output/App"

fn safe_only_path(p: &std::path::Path) -> bool {
    use std::path::Component;
    !p.is_absolute()
        && p.components().all(|c| !matches!(c, Component::ParentDir | Component::Prefix(_)))
}

When it happens

Trigger: Installing a git-URL cask whose url_specs.only_path is absolute (e.g. '/app'), contains '..' segments, or includes a Windows drive/prefix component; git_only_path_source is reached via fetch_git_clone_and_stage after a successful clone.

Common situations: Hand-written or vendored cask JSON where only_path was copied from an absolute build path; typos like '..' meant as relative shorthand; casks authored on Windows with drive-letter paths.

Understand the failure class

Background: Path traversal blocked: "path escapes the workspace" and "outside site root" errors when a path will not stay inside its allowed directory — this error's family across 26 libraries.

Related errors

• brew-cask: structured flight glob '{}' matched outside stage
• unsafe source repository path
• remote task path escapes its Git checkout: {}
• [dotfiles]."{}": target is not a safe OCI path
• brew-cask: invalid {kind} '{value}'

AI-assisted analysis of jdx/mise@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/c28293e0d1369c99. Report an issue: GitHub.