specifying revsets: Is there a good intuition for different argument names?

[Minion3665]

There are 5 different ways to specify revsets to commands, as far as I'm aware.

• -r/--revisions as seen in jj rebase
• -r/--revision (no s) as seen in jj split
• --from/-f as seen in jj squash (which also has -r/--revision (no s))
• just specifying the [REVSETS] as the final argument, as seen in jj abandon or jj describe
• just specifying a single [REVSET] as the final argument, as seen in jj show

Is there an intuition which could help me understand what ways of specifying revsets a command is likely to use without just learning them all?...

...I think -r/--revision or the final [REVSET] argument can only show a single revision - what commands are likely to only show a single thing isn't always clear to me (e.g. git show can show multiple revisions but jj show can only show one). The short version of this (-r) and the positional argument look the same as the --revisions or [REVSETS] so I've not quite learned what takes what there...

...--revisions and --from are paired up with { --destination, --insert-after, --insert-before } and --to so maybe it's things that modify existing revisions vs have the possibility of inserting afterwards/before(?) ... jj squash's --revision maybe doesn't fit this perfectly...

[jennings]

jj rebase can rebase multiple revisions at once, whereas jj split can only split a single revision. That's why one is --revisions and the other is --revision. I always use the short option -r so I don't have to worry about the difference.

jj squash -r foo is shorthand for jj squash --from foo --into foo-. The "primitive" operation is jj squash --from REV --into REV, but squashing a revision into its parent is very common, so -r exists for that use case.

jj new, jj abandon, jj describe, and jj show can all take a -r, so you can type it if it helps your muscle memory. However, those commands will never take a PATH argument (which is always positional), so as a convenience you can leave off the -r.

--revisions...are paired up with { --destination, --insert-after, --insert-before } and --to

This is true, but jj rebase is a bit of a special case because it's so flexible. When you're rebasing, you need to choose what to rebase:

• --source REV to choose the given revisions and all their descendants
• --revisions REV to choose just the given revisions but not their descendants (-r REV means pluck REV out, and rebase any descendants on REV's current parents)
• --branch REV to choose a whole branch of revisions relative to the destination.
• Using none of these is the same as --branch @

And also where to rebase them:

• --destination to rebase on top of the given revision
• --insert-after and --insert-before to insert between some revision and their children/parents.

[Minion3665]

So, if I understand you correctly:

• -r is the normal case for specifying a revision or multiple revisions
• --from and --into (I shortened it to --to in my original message, but into maybe gives better intuition) are about when there's a beginning and a commit you're modifying
• rebase has various ways of specifying extra revisions - but I guess it's not modifying a commit so it wouldn't make much sense for it to be --from/--into anyway(?)
• squash is a special case which has -r as well as its --from and --into, because it has a way to only "specify a revision to squash into its parent" in which case it's only really specifying a revision to act on(?)

So my intuition should be:

• if it modifies a destination commit, I can use --from/--into
• If it doesn't, I can use -r. If a destination is needed, it'll be -d. The most flexible commands get -b/-s/-A/-B but it's relatively unusual to abandon everything above a commit, say, so I'll have to type out the revset manually if I need that

Is this a reasonable summary of what you've said?

[jennings]

Yes!

but it's relatively unusual to abandon everything above a commit, say, so I'll have to type out the revset manually if I need that

FYI, that's as simple as jj abandon xyz:: to abandon xyz and all its descendants.