GitoxideLabs/gitoxide · error

Need a worktree to clean, this is a bare repository

Error message

Need a worktree to clean, this is a bare repository

What it means

`clean` cannot operate on a bare repository because there is no working tree whose untracked files could be removed. The function destructures `repo.workdir()` and bails when it is `None` (bare repo).

Solutions

1. Run clean against a non-bare clone that has a worktree
2. If you meant the bare repo's files, operate on the filesystem directly rather than using `clean`
3. Verify with `repo.workdir().is_some()` before calling and surface a clearer message to the user

Example fix

// before
clean(repo, options, format, progress, &mut out)?;
// after
if repo.workdir().is_none() {
    anyhow::bail!("refusing to clean: repository is bare");
}
clean(repo, options, format, progress, &mut out)?;

if repo.workdir().is_none() {
    anyhow::bail!("cannot clean: bare repository has no worktree");
}

When it happens

Trigger: Calling `clean` with a `gix::Repository` handle opened from (or pointing into) a bare repository — e.g. `gix::open("repo.git")` or `gix::discover` landing on a bare repo.

Common situations: Opening the repository via a bare `GIT_DIR`, discovering from a hook or server-side path, accidentally pointing the CLI at `something.git` instead of the working clone.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• copy-insert requires a worktree
• JSON output isn't implemented yet
• a tree change cannot be amended from the worktree
• cannot delete because another worktree has it checked out
• a detached checked-out root commit cannot be removed

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

Appendix: source

Thrown at gitoxide-core/src/repository/clean.rs:63

        patterns: Vec<BString>,
        Options {
            debug,
            format,
            mut execute,
            ignored,
            precious,
            directories,
            repositories,
            skip_hidden_repositories,
            find_untracked_repositories,
            pathspec_matches_result,
        }: Options,
    ) -> anyhow::Result<()> {
        if format != OutputFormat::Human {
            bail!("JSON output isn't implemented yet");
        }
        let Some(workdir) = repo.workdir() else {
            bail!("Need a worktree to clean, this is a bare repository");
        };

        let index = repo.index_or_empty()?;
        let pathspec_for_dirwalk = !pathspec_matches_result;
        let has_patterns = !patterns.is_empty();
        let mut collect = InterruptibleCollect::default();
        let collapse_directories = CollapseDirectory;
        let options = repo
            .dirwalk_options()?
            .emit_pruned(true)
            .for_deletion(if (ignored || precious) && directories {
                match skip_hidden_repositories {
                    Some(FindRepository::NonBare) => Some(FindNonBareRepositoriesInIgnoredDirectories),
                    Some(FindRepository::All) => Some(FindRepositoriesInIgnoredDirectories),
                    None => Some(Default::default()),
                }
            } else {
                Some(Default::default())

View on GitHub (pinned to e73179060b)