{"record":{"id":"29e8f87f21ed84fd","repo":"gitbutlerapp/gitbutler","slug":"unsupported-repository-reference-format-reftable","errorCode":null,"errorMessage":"unsupported repository reference format: reftable","messagePattern":"unsupported repository reference format: reftable","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/gitbutler-project/src/project.rs","lineNumber":333,"sourceCode":"    pub fn try_project(self) -> anyhow::Result<Project> {\n        match self {\n            AddProjectOutcome::Added(p) => Ok(p),\n            AddProjectOutcome::AlreadyExists(_) => Err(anyhow::anyhow!(\"project already exists\")),\n            AddProjectOutcome::PathNotFound => Err(anyhow::anyhow!(\"project path not found\")),\n            AddProjectOutcome::NotADirectory => {\n                Err(anyhow::anyhow!(\"project path is not a directory\"))\n            }\n            AddProjectOutcome::BareRepository => {\n                Err(anyhow::anyhow!(\"bare repositories are not supported\"))\n            }\n            AddProjectOutcome::NonMainWorktree => {\n                Err(anyhow::anyhow!(\"non-main worktrees are not supported\"))\n            }\n            AddProjectOutcome::NoWorkdir => Err(anyhow::anyhow!(\"no workdir found for repository\")),\n            AddProjectOutcome::NoDotGitDirectory => {\n                Err(anyhow::anyhow!(\"no .git directory found in repository\"))\n            }\n            AddProjectOutcome::ReftableRefFormatUnsupported => Err(anyhow::anyhow!(\n                \"unsupported repository reference format: reftable\"\n            )),\n            AddProjectOutcome::NotAGitRepository(msg) => {\n                Err(anyhow::anyhow!(\"not a git repository: {msg}\"))\n            }\n        }\n    }\n}\n","sourceCodeStart":315,"sourceCodeEnd":342,"githubUrl":"https://github.com/gitbutlerapp/gitbutler/blob/caf1f223d3cfb94488c9198ad34487c6006c648f/crates/gitbutler-project/src/project.rs#L315-L342","documentation":"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.","triggerScenarios":"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.","commonSituations":"Early adopters using reftable-enabled git; repositories cloned/migrated by newer tooling then opened in an app whose gix dependency lacks reftable support.","solutions":["Migrate the repository back to files: `git ref-format migrate --ref-format=files` (recent git), then add it","Re-create/clone the repository without reftable (`git clone --ref-format=files` where supported)","Watch app/gix updates — reftable support lands over time; until then keep such repos out"],"exampleFix":"# before\n# repo created with: git init --ref-format=reftable  ->  add_project rejects it\n\n# after\n$ git ref-format migrate --ref-format=files\n$ # now add the project again","handlingStrategy":"validation","validationCode":"fn is_reftable_repo(path: &Path) -> bool {\n    std::process::Command::new(\"git\")\n        .args([\"-C\", &path.to_string_lossy(), \"config\", \"extensions.refformat\"])\n        .output()\n        .map(|o| o.stdout.trim() == b\"reftable\")\n        .unwrap_or(false)\n}\nif is_reftable_repo(&path) {\n    anyhow::bail!(\"reftable repos unsupported — run: git ref-format migrate --ref-format=files\");\n}","typeGuard":null,"tryCatchPattern":"match add_project(&path, ...) {\n    AddProjectOutcome::ReftableRefFormatUnsupported => {\n        show_migration_hint(\"git ref-format migrate --ref-format=files\")\n    }\n    outcome => outcome.try_project(),\n}","preventionTips":["Check extensions.refformat=reftable before onboarding repos created by bleeding-edge git","Standardize team tooling on the files ref format until the app's gix dependency supports reftable","Watch release notes — once reftable is supported, drop the screen"],"tags":["gitbutler","project","git","reftable","compatibility"],"backgroundTag":"reftable-unsupported","analyzedSha":"caf1f223d3cfb94488c9198ad34487c6006c648f","analyzedAt":"2026-08-20T07:55:40.983Z","schemaVersion":2},"datasetVersion":"2026-08-23T21:17:23.414Z"}