Skip to content

Latest commit

 

History

History
94 lines (72 loc) · 4.54 KB

graph.md

File metadata and controls

94 lines (72 loc) · 4.54 KB

The stakk graph document

stakk graph renders the change graph: --format=pretty (default) for a human, --format=json and --format=json-full as a schema-versioned document for a machine. It is offline — jj only — so it needs no network or credentials.

Nothing in it has been near a forge: no PR numbers, titles, review or CI state, and nothing about what a push would do. stakk learns both during stakk submit's plan phase, and --dry-run prints them.

Two projections, one schema

--format=json is sparse: identifiers, titles and states — enough to drive stakk submit. --format=json-full adds commit bodies, authors and files, which dominate the byte count. Sparse is a strict subset of full (same names, types, values), and both report the same schema_version.

Top level

  • schema_version — currently 3; bumped on breaking schema changes
  • default_branch
  • remotes[] — name, url, host (lowercased, keeping the port of an http(s) URL), repo (owner/repo); host and repo are null when the URL is not <host>/<owner>/<repo>, such as a local path. The document does not say which forge a host runs — that is stakk submit's decision, which is why there is no forge field
  • excluded_bookmarks[] — bookmarks left out because their history contains a merge, which the stacking model does not represent; stakk cannot manage these
  • excluded_heads[] — unbookmarked heads left out for the same reason, each as change_id and short_change_id; a head has no bookmark to name it
  • stacks[] — one per leaf

Stacks

One entry per leaf, segments trunk-to-leaf. Shared ancestor segments are repeated in full in every stack containing them, so each entry is self-contained.

The order is not part of the contract. It follows commit recency, so stacks[0] changes whenever anyone commits, and it is not the TUI's leaf numbering. Identify a stack by its content; committer_timestamp is in the sparse projection so "the most recently modified stack" can be computed rather than assumed.

Segments

A segment is a run of commits ending at a PR boundary.

  • bookmarks[] — one {name} per bookmark on the boundary commit; empty for an unbookmarked head. An object rather than a bare name, so a per-bookmark field can be added without renaming the list
  • commits[] — oldest first, matching the --bookmark-command payload

Several bookmarks on one commit are one boundary: two --keeps naming them is stakk::selection::duplicate_mark.

Commits

In both projections:

  • change_id, short_change_id — either works in the selection flags. The short form is jj's shortest prefix unique right now, so store change_id, or a later run may fail with stakk::selection::rev_unresolvable
  • title — first line of the commit message; empty when there is no description ((no description set) belongs to the pretty renderer, never to the document)
  • committer_timestamp — offset-aware, e.g. 2026-02-19T19:47:54+01:00; the key stack order is derived from. Compare instants, not strings: that value sorts after 2026-02-19T19:00:00Z as text while being twelve minutes earlier
  • is_immutable — cannot take a new bookmark
  • local_bookmark_names[] — unfiltered; includes bookmarks the bookmarks revset excluded, unlike the segment's bookmarks[]
  • is_boundary — the newest commit of its segment
  • is_leaf — the tip of its stack

--format=json-full adds commit_id, description (the full message, title line included), author (name, email, timestamp) and files[]. They are absent from sparse, not null. Stack order follows committer_timestamp, not author.timestamp, because a rebase updates the former.

Stability

Field names, types and the sparse/full subset relationship are covered by schema_version. The order of stacks[] and the pretty format are not.

Changes from version 2

  • remotes[].github is renamed to remotes[].repo and is filled for every <host>/<owner>/<repo> URL, not only GitHub ones.
  • remotes[].host is added.
  • There is no top-level forge field: the graph is offline and does not select a forge.
  • bookmarks[].remote_state is removed. It was derived from jj alone and could not know which remote a submission pushes to, so synced meant "on some remote"; what a push would do is stakk submit --dry-run's answer.
  • excluded_head_count is replaced by excluded_heads[], listing each head's change_id and short_change_id instead of counting them.