graph -> stacks

[Byron]

Produce a datastructure that can represent any commit-graph as segments, which is the level of detail that we are interested in.
These segments can be traversed forward and backwards, and they know the commits that are uniquely assigned to it.
Segments can have inter-segment relations, to help with dealing with related remote tracking branches.

Tasks

• fix remote-failure in gitoxide probably due to invalid ref-name
• map graphs to stacks.
  • single-stack
  • single-stack real-world trials
  • multi-stack workspace
  • assure there is a multi-stack workspace, with overlapping segments
  • multi-stack workspace real-world trials
• document new concepts in Workspace type
• Integrate into ref-info
  • switch as many tests as possible (i.e. those not needing multiple 'virtual' stacks)
  • to_workspace() needs max-segments to avoid fetching info for too many commits, and also max-commits, and integrated 'gas stations' using commit id - do it once single-branch is supported.
• switch legacy conversion over to new implementation and adapt tests (to bring the graph to the UI)
  • make sure these have a limit set
  • make CLI use the new old APIs
• use gix from main

For next PR (wrapup)

• remaining fixes
  • test commit-ownership for 'virtual' branches and remote-ref special case
  • integrated dependent base branch should still show up and respect (or deduce) the archived flag (needs merge-base with main as anchor effectively)
  • add reasonable base as first reachable integrated commit (simplified), maybe the merge-base between all workspace branches?
• multi-goal and integrating local branch of target into search (or not)
  • see if a tweak can help it - after all it shouldn't stop when bumping into something that isn't what it looked for
• add 'insert multi-segments above' capability for more natural reconciled graphs
  • Avoid remote segments inside the workspace, prefer to put them on top.
• split across stacks (those that are resting at the target ref (or maybe the merge base?))
  • We must be able to split out stacks of empty commits resting at the base, that is segments that will be mapped into stacks later. For that we connect them to the governing workspace.
  • This is also related to having a single commit with lots of refs on top, they all need to be split into stacks.
• ⚠️ fix related TODOs and known issues
• ⚠️assure parent-order is correct during traversal (must match parents in merge commits)
• Show how typical segment-walks can now be facilitated with standard algorithms

Not to forget

• There might be an issue with the way it uses searches - a tip with a search might be blocked at an existing commit, discovered by a tip with a different search, and even though the thing it searches is reachable through that, it stops looking.
• ⚠️ the amount of commits of remotes ahead of their local branch doesn't seem to always match git (particularly when it's a lot of them)
• ⚠️handle the archived flag
• ⚠️ current implementation supports multiple workspaces in theory, but it's not tested with them as the underlying ref-metadata is still VB-toml. So before supporting this, we probably already want to have migrated away from vb.toml, to then port the ref-metadata to something that can support more workspaces (also for testing).
• ⚠️ we probably don't correctly handle workspaces that include other workspaces.
• ⚠️ we probably don't handle dot-repositories correctly, by merit of not really having them in mind. At least they shouldn't be in the way of handling normal remotes.

Problems this should solve

This PR should allow us to see if this is the right way to go, as it should solve a couple of problems, all at once:

• make complex commit-graphs graspable
  • Even though there are limits inherent to the tree-view, but it seems to do well enough for our idea of stacks.
• make any commit-graph representable
  • map any such graph to stacks
• make complex workspace updates possible
  • imagine updates to the rebase-engine to be able to transplant complex graphs as well
    • This would work by having well-known operations, supporting only one at a time for now, and then to return
      a pick-list for the rebase engine that can be reviewed before actually running it (i.e. dry-run built-in).

Related

• ref-info: normal workflow #8905

Previous

• graph segmentation spike #8919
• graph segmentation #8935
• Full access needed to create Pull Requests #9096

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
gitbutler-components	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 30, 2025 7:11am

[vercel]

@Byron is attempting to deploy a commit to the GitButler Team on Vercel.

A member of the Team first needs to authorize it.