graph segmentation

[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

• integrate the target branch
  • make sure that integrated commits can be hidden (for instance, new (virtual) stacks shoudn't have a commit. - this is more of a thing for the mapping later where more commit-cleanup is performed.
  • early abort should work as well, check the queue to stop if there is only 'hidden' tips left.
  • optional limit at abort after Y commits have been traversed
    • assure we handle missing target refs (test) (limits apply to workspaces then)
• CLI for opening graphs (with or without workspace, with ref support just like ref-info)
  • make it work for webkit
  • make it work for the linux kernel
  • make limit work correctly in conjunction with remote tracking branches
  • figure out what's going on in the GitLab workspace
    • worst case integrated branch tracking, and inability to go past workspace abort condition
  • fix performance regression
    • entrypoint must be goal
    • linux: doesn't traverse remote branch
    • gitlab: doesn't connect future to present
      • source tracking along with goals
      • possibly: allow goals to not auto-clear their tips if one tip found the goal for longer searches, but assure it can always stop of the goal itself was found. - no such clearing, everything must fully reconcile

Mapping PR

• map graphs to stacks.
  • special handling for limit to handle bad overshoots in large repos.
• Integrate into ref-info
  • make sure all existing tests work and/or are adapted
• GitLab
  • Why does Lane 5 not get picked up as named segment, despite it being in the workspace? Problem is that target didn't fully catch up, and first commit in lane should be seen as integrated.

For next PR (wrapup)

• add 'insert multi-segments above' capability for more natural reconciled graphs.
• 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.
• ⚠️ 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

• ⚠️ 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

[vercel]

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

A member of the Team first needs to authorize it.

[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 21, 2025 6:35pm