From c4849295d64e03cf367ac0fac3ad25e9d1e98bfd Mon Sep 17 00:00:00 2001
From: "chatgpt-codex-connector[bot]"
 <199175422+chatgpt-codex-connector[bot]@users.noreply.github.com>
Date: Mon, 9 Mar 2026 06:54:02 +0800
Subject: [PATCH] document `gitbutler.storagePath`

Document where per-project GitButler state lives and how to override it, including the channel-specific config keys and path constraints.

Motivation: make the new storage path setting discoverable in the debugging docs for users who need to inspect or relocate repository-local GitButler state.

Refs: https://github.com/gitbutlerapp/gitbutler/pull/12646

Co-authored-by: Sebastian Thiel <sebastian.thiel@icloud.com>
---
 content/docs/development/debugging.mdx | 48 ++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/content/docs/development/debugging.mdx b/content/docs/development/debugging.mdx
index 001fa55..78fe383 100644
--- a/content/docs/development/debugging.mdx
+++ b/content/docs/development/debugging.mdx
@@ -151,6 +151,54 @@ The `settings.json` are some top level preferences you've set.
 
 Finally, the `keys` directory holds the SSH key that we generate for you in case you don't want to go through creating your own. It's only used if you want to use it to sign commits or use it for authentication.
 
+### Per-project repository data
+
+Most repository-specific GitButler state lives next to the repository itself, inside the `.git` directory. By default, GitButler stores that data in `.git/gitbutler` for
+release builds, nightly builds and developer builds.
+
+You can override that location with a Git config change, here for the stable build:
+
+```bash title="Terminal"
+❯ git config --local gitbutler.storagePath gitbutler-alt
+```
+
+You can also set it globally if you want all repositories opened by GitButler on that machine to use the same base configuration:
+
+Setting it to a shared directory is useful if the project locations themselves are on a filesystem that doesn't support Sqlite very well,
+like a network drive.
+
+```bash title="Terminal"
+❯ git config --global gitbutler.storagePath /path/to/gitbutler-projects
+```
+
+Setting it to a relative path would force a channel, like Nightly, to reuse the data of stable builds.
+
+```bash title="Terminal"
+❯ git config --global gitbutler.nightly.storagePath gitbutler
+```
+
+The Git config key depends on the app channel:
+
+- Release builds use `gitbutler.storagePath`
+- Nightly builds use `gitbutler.nightly.storagePath`
+- Developer builds use `gitbutler.dev.storagePath`
+
+There are a couple of constraints on the configured path:
+
+- Relative paths are resolved relative to the repository's `.git` directory
+- If the resolved path stays inside `.git`, it must be under a top-level directory whose name starts with `gitbutler`, case-insensitive
+- You cannot point it at `.git` itself
+- If the resolved path ends up outside `.git`, GitButler appends a project-path specific identifier so multiple repositories can share the same base directory safely
+
+For example, these are valid:
+
+```bash title="Terminal"
+❯ git config --local gitbutler.storagePath gitbutler-alt
+❯ git config --local gitbutler.storagePath ../../gitbutler-projects
+```
+
+If you use a path outside `.git`, GitButler treats it as a base directory. For example, `../../gitbutler-projects` becomes something like `../../gitbutler-projects/<project-handle>` after resolution.
+
 ## Linux
 
 ### `glibc` Errors