FR: cli option consistency

[doy]

Is your feature request related to a problem? Please describe.
a lot of jj commands do something to two different revisions, but it is very hard to remember how to do this because there are quite a few different ways that different commands specify them (for instance, from a quick browse of the manual, jj restore uses --from/--to, jj squash uses --from/--into, jj backout uses --revisions/--destination, and jj rebase uses --source/--destination).

additionally, for commands that act on a single revision, it's pretty split between whether that revision must be passed as a plain arg or through --revision.

currently i have to look up the correct option names in either the manual or my shell history pretty much every time i run one of these commands, which doesn't feel great.

Describe the solution you'd like
it'd be really helpful to standardize on a single way to refer to the commits that operations will act on. i don't really have a preference other than that it'd be great if it could be more consistent across different commands.

[arxanas]

• There are several semantic differences between the option names, in such a way that they are meant to be consistent, but I forget the nuances.
  • For example, jj rebase -r X exists and i is different from jj rebase -s, but generally consistent with other -r commands. (It's roughly the same as jj rebase -r 'X::'?)
• I believe that every command which takes a positional revision argument also accepts it via -r for redundancy; file a bug if not.
  • For example, you can write jj new -r X to mean the same as jj new X.

[martinvonz]

Funny timing with #5394 from less than a day ago. As @arxanas said, there are semantic differences between some of them.

additionally, for commands that act on a single revision, it's pretty split between whether that revision must be passed as a plain arg or through --revision.

The reason is that we currently prefer to let positional arguments mean paths. So commands that accept paths (either currently or conceivably) require the revision to be passed via -r. We have #2554 and #3809 about that.

• For example, you can write jj new -r X to mean the same as jj new X.

That's actually an interesting case. I feel like it should accept -d but not -r because it creates the new commit on top of the argument. We talked about this on Discord a while ago. EDIT: We actually allow -d already.

[doy]

i can see --to and --into having different meanings (although it's still hard for me to remember) but what is the intended difference between --from/--source and --to/--destination? i don't really have a good sense of what these semantic differences are supposed to be, and i can't find anything written about it. can you point me to somewhere that describes it?

also, the docs for jj rebase say that -r only rebases the one specific commit - were you thinking of -b or am i confused?

also, if it is intended that -r works everywhere, at the very least the documentation doesn't give any indication of this (for instance, jj abandon and jj describe don't mention -r at all).

[emilazy]

--destination is when you are putting commits on top of an existing commit (e.g. rebase, new, backout, duplicate). --into is when you are modifying the commit itself. It’s about identifying the commit to modify vs. identifying “gaps” to fill in in the commit graph. I personally find that distinction intuitive and appreciate it; OTOH --to vs. --into is a bit of a mess (in part because it’s not clear what the --from corresponding to --into should be; --out-of is the best proposal I’ve heard, but it’s long).

jj rebase -r can take a multi‐commit revset these days. I think the documentation is out of date.

Edit: And --source identifies an entire tree of commits by its base (e.g. jj rebase -s BASE-OF-STACK -d 'main()'); I admit this name isn’t good but can’t immediately think of a better one. I believe that jj rebase -s X is the same as jj rebase -r X::, but I may be wrong.

[martinvonz]

i don't really have a good sense of what these semantic differences are supposed to be, and i can't find anything written about it. can you point me to somewhere that describes it?

We don't have such documentation yet. I suppose we could write some new doc about the CLI design philosophy in general. A less general but quicker solution would be to add an FAQ item or two.

jj rebase -r can take a multi‐commit revset these days. I think the documentation is out of date.

Yes. I'll try to send a patch for that.

I believe that jj rebase -s X is the same as jj rebase -r X::, but I may be wrong.

You're not.

[martinvonz]

I believe that jj rebase -s X is the same as jj rebase -r X::, but I may be wrong.

You're not.

But only assuming X is a single commit. If X is multiple commits, then jj rebase -s X will rebase each commit in the set onto the destination, while jj rebase -r X:: will preserve internal dependencies in the set.

[martinvonz]

See if #5400 helps clarify how the rebase flags work.