terminology for the graph

[joyously]

I read this recent comment

Maybe the confusion is around terminology. What I assumed Yuya meant by "checked out " is in the jj checkout/new sense, i.e. that we create a new working-copy commit on top of some commit. Conversely, "edit" means to make the working copy point to the commit itself. Note that jj new is a combination of "create new commit on top of specified commits" and "edit the new commit" (without --no-edit). Does that clarify?

and couldn't help but think that it is yet another confusing reference to "top" and how a descendant is above the parent in the graph. I understand the word descendant in the sense of hierarchy, but in the graph, it doesn't descend.

There have also been mentions of "moving branches forward", and there are next and prev (are these commands?).

I'm not a visual learner, so maybe I put more emphasis on words. I have a hard time with the mental model of the graph with all these contradictory words.

[arxanas]

To comment on your referenced points directly (although it sounds like you understand everything fine and are pointing out the general lack of understandability):

• "On top of" refers to a child commit. Perhaps "top" refers to a gravity-based metaphor, i.e. if you stack an item on top of another item, then the top-most item has no dependencies and therefore corresponds to a leaf of the dependency graph.
  • git-branchless directly refers to this notion in its "commit stack" metaphor — which is then directly opposed to its default rendering direction 🤣 (see below).
  • Maybe it refers to some other metaphor. I put a bandage on "top" of a wound regardless of how the wound is oriented in space.
• "Forward" refers to towards the leaves of the graph, which is the same as "topward" in the previous sense, I suppose.
  • git-branchless inverts the default graph ordering to match what I perceive to be most useful in the terminal, which is that the newest/leafmost nodes appear nearest to the next shell prompt. Then "top" obviously becomes exactly inverted from its literal rendering in the terminal, but the "ancestor"/"descendant" model aligns with this.
  • I think the Interactive Smartlog ("ISL") (from Sapling) matches the sl/jj ordering of putting the newest nodes at the top, but for the ISL it makes sense because the default rendering area in a scrollable window is at the top, unlike the terminal where the most-recently-rendered output appears at the bottom.
• "Next"/"previous" must refer to the code review or patch application order, which is the topological order (see later). It's not obvious what these terms mean by themselves, but the meaning is in fact precise.

You make an interesting point. I don't know if there exists unambiguous concise terminology for directions in DAGs.

• I guess for jj it would be consistent and precise to write "headward" and "rootward", but I've never seen terms like that used anywhere.
• You could say "leafward" to mean "headward" as well and reuse "leaf" terminology for trees/graphs, but I don't know what the opposite direction would be called.
• "Parentward"/"childward" or "ancestorward"/"descendantward" work but are wordy/clumsy?
• There is the conceptual problem that the "direction" of the DAG is typically opposite between the implementation and how novices think of it. In the prototypical DAG-based SCM, the DAG encodes parent pointers, but, realistically, most people are concerned with the child relation and envision the opposite direction by default.
• I guess the "topological ordering" is consistent even between the implementation and common mental models. Everyone agrees that commits have to be applied before their descendants. "Topoforward"/"topoafter"/"topolater" sound kind of clumsy, though. But maybe "before" and "after" are unambiguous as they must refer to the topological ordering? "Next" and "previous" work similarly but aren't as obvious.

[amiryal]

"Next"/"previous" must refer to the code review or patch application order

But maybe "before" and "after" are unambiguous as they must refer to the topological ordering?

I think these work better (especially “before” and “after”) because, rather than a spatial sense, they also convey a strong temporal sense, as in “patch application order”, which is most intuitive to reason about.

[Zambito1]

I also find temporal terms like "before" and "after" to be the most intuitive.

[martinvonz]

We use "before" and "after" in jj new --insert-{before,after}. What contexts are we talking about here? Are you (anyone) suggesting that we generally replace "descendants" by "later revisions", for example? Replacing "parent commit/revision" by "previous commit/revision"? I'm not completely against that, but it would be a pretty big change.

[Zambito1]

I did notice that with the new subcommand, and I liked it :)

I actually see "ancestors" and "descendants" as temporal as well though. Ancestors are created before their descendants.

I don't have any changes to recommend, just throwing in my 2c :)

[joyously]

I'm not suggesting any changes, although there might be something that can be done to avoid the mixture of directional terms between the docs and the CLI output. As I said, it's all about the mental model, as this other person says (in Pijul Zulip):

for me, the main thing I can;t deal with git is trying to visualise this complex abstract graph when I have 50 other things going on in the actual work I need to do - I.e. I want my VCs to involve as little thinking as possible and just to work as effortlessly as possible.

[joyously]

One way I've found to check the docs for terminology problems is to use Google Translate. Either switch to another language and see if it still makes sense, or run it through a few languages and back to English and see if it still makes sense.