{"record":{"id":"7bd4b74181d28141","repo":"GitoxideLabs/gitoxide","slug":"refusing-to-checkout-index-into-existing-directory","errorCode":null,"errorMessage":"Refusing to checkout index into existing directory '{}' - remove it and try again","messagePattern":"Refusing to checkout index into existing directory '(.+?)' - remove it and try again","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"gitoxide-core/src/index/checkout.rs","lineNumber":32,"sourceCode":"pub fn checkout_exclusive(\n    index_path: impl AsRef<Path>,\n    dest_directory: impl AsRef<Path>,\n    repo: Option<PathBuf>,\n    mut err: impl std::io::Write,\n    mut progress: impl NestedProgress,\n    should_interrupt: &AtomicBool,\n    index::checkout_exclusive::Options {\n        index: Options { object_hash, .. },\n        empty_files,\n        keep_going,\n        thread_limit,\n    }: index::checkout_exclusive::Options,\n) -> anyhow::Result<()> {\n    let repo = repo.map(gix::discover).transpose()?;\n\n    let dest_directory = dest_directory.as_ref();\n    if dest_directory.exists() {\n        bail!(\n            \"Refusing to checkout index into existing directory '{}' - remove it and try again\",\n            dest_directory.display()\n        )\n    }\n    std::fs::create_dir_all(dest_directory)?;\n\n    let mut index = parse_file(index_path, object_hash)?;\n\n    let mut num_skipped = 0;\n    let maybe_symlink_mode = if !empty_files && repo.is_some() {\n        gix::index::entry::Mode::DIR\n    } else {\n        gix::index::entry::Mode::SYMLINK\n    };\n    for entry in index.entries_mut().iter_mut().filter(|e| {\n        e.mode\n            .contains(maybe_symlink_mode | gix::index::entry::Mode::DIR | gix::index::entry::Mode::COMMIT)\n    }) {","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/GitoxideLabs/gitoxide/blob/e73179060badf27222d790981fac3f84c1830a7e/gitoxide-core/src/index/checkout.rs#L14-L50","documentation":"Thrown by gitoxide-core's exclusive index checkout (`index::checkout_exclusive`) when the destination directory already exists on disk. This command is meant to create the destination itself, so it refuses to overwrite or merge into pre-existing content to avoid clobbering user data.","triggerScenarios":"Calling `gix repo checkout-exclusive` (or the `checkout_exclusive` function) with a `dest_directory` path that already exists on the filesystem, even if the directory is empty.","commonSituations":"Re-running a failed checkout without cleaning up; pointing at a directory created by a previous run or by another tool; scripting where the target path is reused between runs.","solutions":["Delete or move the existing destination directory, then re-run the checkout","Choose a fresh destination directory path","In scripts, `rm -rf` the target (carefully) before invoking the checkout","Check `dest.exists()` in the caller and pick a unique path"],"exampleFix":"// before\ngix repo checkout-exclusive --destination ./worktree\n// after\nrm -rf ./worktree\ngix repo checkout-exclusive --destination ./worktree","handlingStrategy":"validation","validationCode":"use std::path::Path;\nfn prepare_dest(dest: &Path) -> std::io::Result<()> {\n    if dest.exists() {\n        std::fs::remove_dir_all(dest)?; // or bail in the caller\n    }\n    Ok(())\n}","typeGuard":null,"tryCatchPattern":"match index::checkout_exclusive::checkout(/* args */) {\n    Ok(()) => /* proceed */,\n    Err(e) if e.to_string().contains(\"Refusing to checkout index into existing directory\") => {\n        std::fs::remove_dir_all(dest)?;\n        // retry once\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["Always use a fresh destination directory per run","Clean up the destination in scripts before checkout","Never reuse a worktree path between checkout runs without deleting it first"],"tags":["git","checkout","filesystem","cli"],"backgroundTag":"file-already-exists","analyzedSha":"e73179060badf27222d790981fac3f84c1830a7e","analyzedAt":"2026-09-08T11:26:50.865Z","contentChangedAt":"2026-09-08T11:26:50.865Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}