Store ad-hoc branch order metadata by estib-vega · Pull Request #14513 · gitbutlerapp/gitbutler

estib-vega · 2026-06-29T12:28:28Z

Store the branch ordering metadata for single branch mode, and use that to inform the ordering in the but-graph and projection.

Changes

This creates a new DB table with branch orderings.
The orderings are read and used in order to determine the order of branches that point to the same commit in ad-hoc workspaces (single branch mode)

This is part 1 of 2 in a stack made with GitButler:

Copilot

Pull request overview

This PR introduces durable storage and consumption of ad-hoc (single-branch mode) dependent-branch ordering metadata by persisting refname parent pointers in the project SQLite database and using that ordering during graph post-processing to preserve/split same-tip dependent branches.

Changes:

Add a new branch_order SQLite table (with read/write handles) and migrations/tests in but-db.
Add RefMetadata APIs for reading/writing ad-hoc branch stack order and a BranchOrderMetadata implementation that combines legacy TOML metadata with DB-backed ordering.
Teach but-graph post-processing and workspace projection to consume persisted ad-hoc ordering (e.g., keeping empty top segments and handling ordered lower bounds).

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
crates/but-core/src/lib.rs	Extends `RefMetadata` with branch stack order read/write capability (default no-op / unsupported).
crates/but-meta/src/lib.rs	Re-exports `BranchOrderMetadata` from the legacy module for consumers under the `legacy` feature.
crates/but-meta/src/legacy/mod.rs	Adds `BranchOrderMetadata` combining legacy TOML metadata with DB-backed branch ordering persistence.
crates/but-db/src/handle.rs	Adds read-only “open existing DB” helpers to avoid creating/migrating DBs for projections.
crates/but-db/src/lib.rs	Exposes branch-order handles and registers branch-order migrations.
crates/but-db/src/table/mod.rs	Wires the new `branch_order` table module into the table registry.
crates/but-db/src/table/branch_order.rs	Implements the `branch_order` table schema, read path (`order_for_reference`), and write path (`set_order`, `remove_reference`).
crates/but-db/tests/db/migration.rs	Updates the migration snapshot to include the `branch_order` table/index and schema version.
crates/but-db/tests/db/handle.rs	Adds coverage for read-only DB open behavior (doesn’t create DB; observes existing DB).
crates/but-db/tests/db/table/mod.rs	Registers the new branch-order table tests module.
crates/but-db/tests/db/table/branch_order.rs	Adds unit tests for branch-order chain updates/removals and cycle degradation behavior.
crates/but-graph/src/lib.rs	Adds `ad_hoc_branch_stack_orders` state to retain ordered refs for downstream projection decisions.
crates/but-graph/src/init/mod.rs	Adds overlay plumbing for branch stack order overrides during traversal redo.
crates/but-graph/src/init/overlay.rs	Adds in-memory overrides for branch stack order and routes reads through overlay before metadata backend.
crates/but-graph/src/init/post.rs	Uses persisted ad-hoc ordering to split same-tip refs into explicit empty segments and records involved orders.
crates/but-graph/src/projection/workspace/init.rs	Uses recorded ad-hoc orders to treat ordered lower bounds specially and to keep ordered empty segments from being pruned.
crates/but-graph/tests/graph/init/mod.rs	Updates graph init fixtures to include the new `ad_hoc_branch_stack_orders` field.

estib-vega · 2026-06-30T07:06:01Z

`but-graph` / projection explainer

The but-graph part of this PR teaches graph construction how to consume persisted ad-hoc branch order metadata, then lets workspace projection decide which part of that ordered graph should be visible from the current entrypoint.

What Git gives us

In single-branch/ad-hoc mode, Git can represent refs and commits, but it cannot represent that one empty branch is intentionally above another branch when both refs point to the same commit.

For example, Git only knows this:

refs/heads/top    -> commit X
refs/heads/bottom -> commit X

It does not know whether top should appear above bottom. The new branch-order metadata supplies that missing intent:

[top, bottom]

Step by step

Graph is built from the requested entrypoint, such as top or bottom. At this point, same-tip refs naturally collapse around the same commit because that is what Git stores.
During graph post-processing, ad_hoc_branch_stack_upgrades() looks for persisted branch order metadata for the entrypoint ref.
The post-processing only applies this metadata when it is safe:
- the entrypoint is a local branch,
- metadata has an order containing that branch,
- at least two ordered refs still exist,
- at least two ordered refs point to the same commit as the bottom ordered ref.
Missing metadata refs are filtered out. If metadata says [top, missing, bottom] and missing no longer exists, graph does not create a phantom branch.
The last ref in the order is treated as the bottom branch. For [top, middle, bottom], only bottom owns the actual commit.
The same-tip ref bundle is rebuilt into explicit graph segments:

top(empty)
  -> middle(empty)
    -> bottom(commit X)

This lets graph preserve the intended empty-branch shape without requiring managed workspace metadata.

The graph stores the effective order in ad_hoc_branch_stack_orders. Workspace projection uses that to avoid treating ordered lower branches as ordinary local-branch boundaries.

Projection rule

Projection starts from the actual entrypoint. It does not pull branches above the entrypoint into the visible single-branch workspace.

So with metadata [top, bottom]:

If the entrypoint is top, projection shows top and bottom.
If the entrypoint is bottom, graph still knows top is above it, but projection shows only bottom.

That gives us this split of responsibility:

post.rs:
  reshapes same-tip refs into ordered empty graph segments

projection/workspace/init.rs:
  decides which ordered segments are visible from the current entrypoint

The added graph tests cover same-tip ordering, bottom-entrypoint projection, three-branch middle preservation, and missing metadata refs not creating phantom branches.

Copilot

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9a575ee0ba

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copilot

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.

Copilot

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.

+        self.ad_hoc_branch_stack_orders.push(matching_refs.clone());
+
+        let bottom_segment_id =
+            ad_hoc_order_bottom_segment_id(self, bottom_ref.as_ref(), bottom_commit_id);
+        let Some(bottom_segment_id) = bottom_segment_id else {
+            return Ok(());
+        };
+
+        rebuild_same_tip_segment_chain_by_branch_order(
+            self,
+            bottom_segment_id,
+            matching_refs,
+            entrypoint_ref.as_ref(),
+            meta,
+            worktree_by_branch,
+        )?;
+        Ok(())


estib-vega mentioned this pull request Jun 29, 2026

Support ad-hoc dependent branch ordering #14376

Draft

github-actions Bot added the rust Pull requests that update Rust code label Jun 29, 2026

estib-vega requested a review from Copilot June 29, 2026 12:35

Copilot started reviewing on behalf of estib-vega June 29, 2026 12:35 View session

Copilot AI reviewed Jun 29, 2026

View reviewed changes

Comment thread crates/but-db/src/table/branch_order.rs

estib-vega force-pushed the metadata-storage branch from 4f53898 to 9decbea Compare June 30, 2026 06:59

estib-vega requested a review from Copilot June 30, 2026 07:07

Copilot started reviewing on behalf of estib-vega June 30, 2026 07:07 View session

Copilot AI reviewed Jun 30, 2026

View reviewed changes

estib-vega force-pushed the metadata-storage branch from 9decbea to 9a575ee Compare June 30, 2026 08:06

estib-vega marked this pull request as ready for review June 30, 2026 09:41

Copilot AI review requested due to automatic review settings June 30, 2026 09:41

estib-vega requested review from Byron, Caleb-T-Owens, jonathantanmy2 and krlvi as code owners June 30, 2026 09:41

Copilot started reviewing on behalf of estib-vega June 30, 2026 09:41 View session

chatgpt-codex-connector Bot reviewed Jun 30, 2026

View reviewed changes

Comment thread crates/but-graph/src/init/post.rs Outdated

Copilot AI reviewed Jun 30, 2026

View reviewed changes

Comment thread crates/but-graph/src/init/post.rs Outdated

estib-vega force-pushed the metadata-storage branch from 9a575ee to fdff025 Compare June 30, 2026 12:54

Store ad-hoc branch order metadata

b80da36

Copilot AI review requested due to automatic review settings June 30, 2026 14:58

estib-vega force-pushed the metadata-storage branch from fdff025 to b80da36 Compare June 30, 2026 14:58

Copilot started reviewing on behalf of estib-vega June 30, 2026 14:59 View session

Copilot AI reviewed Jun 30, 2026

View reviewed changes

krlvi approved these changes Jul 1, 2026

View reviewed changes

estib-vega merged commit f3306f5 into master Jul 1, 2026
40 checks passed

estib-vega deleted the metadata-storage branch July 1, 2026 15:00

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Store ad-hoc branch order metadata#14513

Store ad-hoc branch order metadata#14513
estib-vega merged 1 commit into
masterfrom
metadata-storage

estib-vega commented Jun 29, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

estib-vega commented Jun 30, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

estib-vega commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

estib-vega commented Jun 30, 2026

but-graph / projection explainer

What Git gives us

Step by step

Projection rule

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

estib-vega commented Jun 29, 2026 •

edited

Loading

`but-graph` / projection explainer