gitbutlerapp/gitbutler · error

non-main worktrees are not supported

Error message

non-main worktrees are not supported

What it means

try_project maps AddProjectOutcome::NonMainWorktree to this error. The directory is a valid git worktree but not the main one (a linked worktree created via `git worktree add`), which GitButler does not support for project management.

Solutions

  1. Add the main repository directory (the one containing the full `.git` directory, not a `.git` file).
  2. Find the main worktree: run `git worktree list` inside the folder and use the entry marked (bare) main/first row's path.
  3. If you only need this branch, open the main worktree in GitButler and manage the branch there via virtual branches instead.

Example fix

// before
let project = add_project(worktree_path)?.try_project()?;
// after
let git_meta = worktree_path.join(".git");
if git_meta.is_file() {
    // linked worktree: use the main worktree instead
    return Err("add the main worktree, not a linked one".into());
}
let project = add_project(worktree_path)?.try_project()?;
Defensive patterns

Strategy: validation

Validate before calling

fn is_main_worktree(path: &std::path::Path) -> bool {
    // linked worktrees have a .git FILE pointing at the main repo
    let git = path.join(".git");
    git.is_dir()
}

Try / catch

match outcome.try_project() {
    Err(e) if e.to_string() == "non-main worktrees are not supported" => {
        // resolve main worktree via `git worktree list` and add that
        add_main_worktree(&path)?;
    }
    other => other,
}

Prevention

When it happens

Trigger: Adding a directory created with `git worktree add <path> <branch>`, or a worktree whose `.git` is a file pointing back to the main repository's worktrees metadata.

Common situations: Developers using multiple checkouts of one repo, adding a feature-branch worktree folder, or pointing GitButler at a CI checkout directory.

Related errors

AI-assisted analysis of gitbutlerapp/gitbutler@58e5313667 (2026-09-18). Data as JSON: /api/errors/c2dd313f5f0af98b. Report an issue: GitHub.

Appendix: source

Thrown at crates/gitbutler-project/src/project.rs:327

            AddProjectOutcome::Added(p) => p,
            _ => panic!("called `AddProjectOutcome::unwrap_project()` on a non-project outcome"),
        }
    }

    /// Try to get the `Project`, returning an error if it was not added.
    pub fn try_project(self) -> anyhow::Result<Project> {
        match self {
            AddProjectOutcome::Added(p) => Ok(p),
            AddProjectOutcome::AlreadyExists(_) => Err(anyhow::anyhow!("project already exists")),
            AddProjectOutcome::PathNotFound => Err(anyhow::anyhow!("project path not found")),
            AddProjectOutcome::NotADirectory => {
                Err(anyhow::anyhow!("project path is not a directory"))
            }
            AddProjectOutcome::BareRepository => {
                Err(anyhow::anyhow!("bare repositories are not supported"))
            }
            AddProjectOutcome::NonMainWorktree => {
                Err(anyhow::anyhow!("non-main worktrees are not supported"))
            }
            AddProjectOutcome::NoWorkdir => Err(anyhow::anyhow!("no workdir found for repository")),
            AddProjectOutcome::NoDotGitDirectory => {
                Err(anyhow::anyhow!("no .git directory found in repository"))
            }
            AddProjectOutcome::ReftableRefFormatUnsupported => Err(anyhow::anyhow!(
                "unsupported repository reference format: reftable"
            )),
            AddProjectOutcome::NotAGitRepository(msg) => {
                Err(anyhow::anyhow!("not a git repository: {msg}"))
            }
        }
    }
}

View on GitHub (pinned to 58e5313667)