UX CLI terms consistency

[ggirelli]

Hi there, I am brand new to the jj world and loving it so far! I just noticed that some commands use the --source/--destination terminology (e.g., jj rebase) while other ones use --from/--to (e.g., jj bookmark move, jj squash). Is that intentional? Do you think it might improve UX if the terminology was consistent? (it looks like from/to is more common). I personally keep forgetting which command uses which and end up having to fix my commands all the time 🤦🏻‍♂️

[joyously]

According to the CHANGELOG.md,
Release 0.24.0 added --from/--to to 5 commands.
Release 0.8.0 added -s and -b to rebase.
Release 0.7.0 added --from/--to to diffedit.
Release 0.5.0 added --to to restore.

According to the CLI reference, --source is only on fix, rebase, and simplify-parents. All of these are for specifying a revset.
--destination is on duplicate, rebase, revert, and split. All of these are for revsets (and all say they go "onto").
--from and --to are on absorb, bookmark move, diff, diffedit, interdiff, op diff, restore, and squash. Most of the --from options can be revsets, but --to is usually singular (and can mean "into").

Which ones would make sense to change?

[ggirelli]

Thank you for the prompt reply! I am not entirely sure to be honest, as the intent behind the different semantic is not clear to me at the moment.

[jennings]

--from and --to/--into are used in commands that move file contents/diffs from one revision to another, or compare contents across revisions:

• jj squash
• jj diff
• jj restore

On the other hand, --source, --destination, --insert-after, and --insert-before are used in commands that mutate the commit graph by inserting, removing, and reordering revisions:

• jj rebase
• jj new
• jj duplicate

One couldn't really be replaced with the other because reordering revisions has more possibilities. When choosing revisions to rebase, you can:

• -s REV: rebase REV and all its descendants
• -r REV: rebase REV only, plucking it from whatever lineage it currently is in
• -b REV -d BASE: same as -r BASE..REV but more convenient to type

It's not obvious which of these should be --from.

(Note: jj fix is an exception. It operates on file contents, but it only makes sense to run it on a revision and all its descendants. That's why it uses -s.)

[jennings]

Hrm, I forgot about bookmarks.

This is just my perspective, but I don't view it as commit graph manipulation because the commit IDs don't change at all. You're attaching metadata to commits, so I think of bookmarks as being their own thing.

None of --destination, --insert-after, or --insert-before make sense for moving bookmarks because bookmarks are always assigned onto a specific commit, not "as a child of" a commit (which is how --destination is always used) or "between commits" (like --insert-after and --insert-before).

This might be something you just need to memorize for now, and after using jj for a while it will become clearer whether a command probably wants --from/--to or wants -s/-r/-d/-A/-B.

[yuja]

There's a related issue. #5397
We've also discussed renaming --destination to --onto somewhere else.

My understanding is that --from/--to are general-purpose flags, but --source/--base/--destination have implication on the graph structure.

[ggirelli]

Hi! I think the intent behind the semantic choice is now clear enough that I will not keep hitting the wrong flags 😊 thank you both! I will close this thread now.

[martinvonz]

The question comes up every now and then, so we should document it somewhere. Maybe we can add something to the top of https://jj-vcs.github.io/jj/latest/cli-reference/.

[jennings]

It seems jj squash and friends just gained -d, -A, and -B, so that makes my answer here confusing.

For those commands, they seem to create a new, empty change and then squash into it:

$ jj squash --destination DEST

# same as:

$ jj new --no-edit DEST
$ jj squash --into $NEW_CHANGE_ID