GitoxideLabs/gitoxide · error

at least one directory level

Error message

at least one directory level

What it means

In `gix/src/worktree/mod.rs`, the internal `id()` helper derives a worktree name from `git_dir.file_name()` and expects the git dir to have at least one path component. If the git dir is the filesystem root (e.g. `/`) or otherwise has no file name, the expect panics. This helper only runs when a common dir exists and the parent looks like a `worktrees` directory, so a root-level git dir breaks the assumption.

Solutions

1. Ensure the worktree git dir (`.git/worktrees/<name>` per the common dir) is a normal named directory, not a mount root.
2. Check `git_dir.file_name()` is `Some` before calling APIs that derive the worktree id, or use `try_id`-style logic upstream.
3. Report a bug to gitoxide if a standard `git worktree add` layout triggers this.

Example fix

// before
let name = git_dir.file_name().expect("at least one directory level");
// after (caller-side guard)
if git_dir.file_name().is_none() { return Ok(None); } // skip: git dir has no name component

let git_dir = proxy.git_dir();
assert!(git_dir.file_name().is_some(), "git dir must not be a root path");

fn has_name(p: &std::path::Path) -> bool { p.file_name().is_some() }

When it happens

Trigger: Opening a linked worktree whose git dir resolves to a path with no final component (root path), e.g. exotic setups mounting `.git/worktrees/<name>` content at `/`; calling `repo.worktrees()`/`worktree::Proxy::id()` paths on such a layout.

Common situations: Container/chroot layouts where the git dir is `/`; corrupted `.git/worktrees` metadata; deeply custom CI setups linking worktrees at unusual paths.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• worktrees/ parent dir
• no illformed UTF-8
• no illformed UTF-8
• Tried to use as tree, but was
• Tried to use as commit, but was

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

Appendix: source

Thrown at gix/src/worktree/mod.rs:109

    /// Return the ID of the repository worktree, if it is a linked worktree, or `None` if it's a linked worktree.
    pub fn id(&self) -> Option<&BStr> {
        id(self.parent.git_dir(), self.parent.common_dir.is_some())
    }

    /// Returns true if the `.git` file or directory exists within the worktree.
    ///
    /// This is an indicator for the worktree to be checked out particularly if the parent repository is a submodule.
    pub fn dot_git_exists(&self) -> bool {
        self.path.join(gix_discover::DOT_GIT_DIR).exists()
    }
}

pub(crate) fn id(git_dir: &std::path::Path, has_common_dir: bool) -> Option<&BStr> {
    if !has_common_dir {
        return None;
    }
    let candidate = gix_path::os_str_into_bstr(git_dir.file_name().expect("at least one directory level"))
        .expect("no illformed UTF-8");
    let maybe_worktrees = git_dir.parent()?;
    (maybe_worktrees.file_name()?.to_str()? == "worktrees").then_some(candidate)
}

///
pub mod proxy;

///
#[cfg(feature = "index")]
pub mod open_index {
    /// The error returned by [`Worktree::open_index()`][crate::Worktree::open_index()].
    #[derive(Debug, thiserror::Error)]
    #[expect(missing_docs)]
    pub enum Error {
        #[error(transparent)]
        ConfigIndexThreads(#[from] crate::config::key::GenericErrorWithValue),
        #[error(transparent)]

View on GitHub (pinned to e73179060b)