gitbutlerapp/gitbutler · error

unsupported repository reference format: reftable

Error message

unsupported repository reference format: reftable

What it means

AddProjectOutcome::ReftableRefFormatUnsupported mapped through try_project: the repository stores its references in the newer reftable format (git config extensions.refformat=reftable / init with --ref-format=reftable), which the gix version bundled here cannot read. The repository is a git repo, but its ref backend is unsupported, so onboarding is refused rather than corrupting it.

Source

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

    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 caf1f223d3)

Solutions

  1. Migrate the repository back to files: `git ref-format migrate --ref-format=files` (recent git), then add it
  2. Re-create/clone the repository without reftable (`git clone --ref-format=files` where supported)
  3. Watch app/gix updates — reftable support lands over time; until then keep such repos out

Example fix

# before
# repo created with: git init --ref-format=reftable  ->  add_project rejects it

# after
$ git ref-format migrate --ref-format=files
$ # now add the project again
Defensive patterns

Strategy: validation

Validate before calling

fn is_reftable_repo(path: &Path) -> bool {
    std::process::Command::new("git")
        .args(["-C", &path.to_string_lossy(), "config", "extensions.refformat"])
        .output()
        .map(|o| o.stdout.trim() == b"reftable")
        .unwrap_or(false)
}
if is_reftable_repo(&path) {
    anyhow::bail!("reftable repos unsupported — run: git ref-format migrate --ref-format=files");
}

Try / catch

match add_project(&path, ...) {
    AddProjectOutcome::ReftableRefFormatUnsupported => {
        show_migration_hint("git ref-format migrate --ref-format=files")
    }
    outcome => outcome.try_project(),
}

Prevention

When it happens

Trigger: add_project on a repo created by a recent git with `git init --ref-format=reftable` or migrated via `git ref-format migrate`; repos produced by bleeding-edge git builds where reftable becomes default in experimental setups.

Common situations: Early adopters using reftable-enabled git; repositories cloned/migrated by newer tooling then opened in an app whose gix dependency lacks reftable support.

Related errors

AI-assisted analysis of gitbutlerapp/gitbutler@caf1f223d3 (2026-08-20). Data as JSON: /api/errors/29e8f87f21ed84fd. Report an issue: GitHub.