help text for rebase is inconsistent

[joyously]

Description

My reading of the jj help rebase text is perhaps tainted by seeing -r used on other commands as plural, so I equate it with "revset". I got confused by the first paragraph saying that -s is for "a revision and its descendants" followed immediately by -r for "a single commit". They seemed backward to me, so the examples were a bit much especially since they take up enough room that I can't fit the first paragraph explanation on the same screen as the option descriptions. In addition, the example graphs have visible Markdown taking up space.
The option description says that -s is for source and -r is for revisions (plural).

This is one explanation where using both "commit" and "revision" is very confusing.
The help needs to say a little more about rebase than simply "move revisions to different parents", to give at least a hint of what changes and/or what consequences or limits there are since novice users need that.

Steps to Reproduce the Problem

1. jj help rebase
2. compare first paragraph to option definitions

Expected Behavior

I expect option letters to make sense.

Actual Behavior

Option letters represent renamed concepts ( -b for branch ), no match for the letter ( -s for "a revision and its descendants" ), and different plurality ( -r is "single commit" versus "--revisions" )

Specifications

• Platform: Ubuntu Studio 24.04
• Version: jj 0.23.0

[arxanas]

Link for reference: https://jj-vcs.github.io/jj/v0.24.0/cli-reference/#jj-rebase

My reading of the jj help rebase text is perhaps tainted by seeing -r used on other commands as plural, so I equate it with "revset".

I think the documentation is misleading and I believe -r can take an arbitrary revset, not just a single revision, as you expected.

• This is useful in case you want to "splice out" a set of commits and rebase it.
• It's corroborated later in the docs when it refers to "specified revisions".

I got confused by the first paragraph saying that -s is for "a revision and its descendants" followed immediately by -r for "a single commit". They seemed backward to me, so the examples were a bit much especially since they take up enough room that I can't fit the first paragraph explanation on the same screen as the option descriptions. In addition, the example graphs have visible Markdown taking up space.

[historical note] I suspect the -b and -s options were taken directly from Mercurial, and -r may not have existed at first, hence the documentation might have been written in the "wrong" order.

I agree that, from a conceptual perspective, it probably makes sense to discuss the -r case first, and define -s and -b flags in terms of that behavior.

I personally don't like -b/--branch and -s/--source as names that much.

• I don't have better naming ideas.
• Maybe it would even be possible to remove them altogether if we had better revset syntax.
  • How much do we benefit from being able to write -s 'foo()' instead of `-r 'foo()::'?
  • It seems like mostly a matter of syntax and operator precedence. If we had a "pipeline" or postfix function application operator, then perhaps we could write complicated_expr() |> :: or something like that, without having to fiddle with the syntax too much.

[tangential] I personally have found that the default of -b @ is usually not what I want, since it oftentimes intersects immutable commits. That concept also came into being after -b was created, I believe.

This is one explanation where using both "commit" and "revision" is very confusing.

Agreed. We should definitely be consistent. I think "revision" is a better term to use everywhere.

The help needs to say a little more about rebase than simply "move revisions to different parents", to give at least a hint of what changes and/or what consequences or limits there are since novice users need that.

Agreed. I see now that it actually doesn't mention anything about reapplying patches, so from the specification in the docs here, one could be misled into thinking that it only modifies the graph structure without changing any of the snapshots/trees.

[jennings]

• How much do we benefit from being able to write -s 'foo()' instead of `-r 'foo()::'?

jj fix only accepts -s and I find that to be a helpful reminder that it will always operate on descendants too. I would have taken longer to memorize what that means if I didn’t already have the knowledge from jj rebase.

[tangential] I personally have found that the default of -b @ is usually not what I want, since it oftentimes intersects immutable commits. That concept also came into being after -b was created, I believe.

I use the default all the time, we do GitHub flow so I habitually run jj rebase -d main to get my feature branches up to date.