RFC: Rename jj backout to jj revert

[zx8]

Forking this discussion from #5676 (comment)

The name of this subcommand is something that stood out to me from the moment I started using jj and instinctively looked for a revert subcommand in the output of jj --help. Revert feels like a naturally better name to me, coming from Git.

---

Note

Does anyone strongly prefer "back out"? Our current template is identical to Git's except that Git says "revert". I find "back out" somewhat awkward and not more accurate, so I would prefer we adjust the default template and rename the command.

— @emilazy in #5676 (comment)

---

Note

FWIW, I agree @emilazy

It also mildly irks me that the subcommand is jj backout while the verb form is two separate words "back out".

"Revert" is both more familiar to Git users and a single word in both forms.

— @zx8 in #5676 (comment)

---

Note

@martinvonz said in #5397 (comment):

revert is confusing for hg users (hg revert is jj restore). We could still use that, or we could use reverse. Another option is rollback (or roll-back to be more grammatically correct).

Personally I think a little confusion for Mercurial users an acceptable cost for what I think is the better name (we confuse Git users a fair bit already!). I don’t mind reverse either, but I think it’s more ambiguous (maybe it could reverse commit ordering?) and the Git terminology is good enough that we can just reuse it.

— @emilazy in #5676 (comment)

---

Looking into things a bit further, StackOverflow conducted a survey in 2023 that revealed around 1% of developers use Mercurial. I don't think this is a compelling enough reason to fumble around trying to find a different name (reverse, rollback, roll-back, etc. were floated @ #5397 (comment)) to avoid confusing such a small percentage of VCS users.

So, what does everyone think about renaming jj backout to jj revert?

[PhilipMetzger]

In my opinion both backout and rollback are a more appropriate name for the command since Jujutsu is no Git descendant (its command-line interface is shaped like Mercurial) and while familiarity is "great" for people coming from Git, the project shouldn't optimize for it.

[joyously]

To me, revert sounds like it moves a pointer in a stack of things (sort of like an undo), which in jj is restore?
The description suggests invert.
I would not have guessed backout to be a match for the description. It seems like abandon is better suited for it.
Maybe there are too many commands, and several should be condensed to one command with options, much like how squash was.

[emilazy]

In my opinion both backout and rollback are a more appropriate name for the command since Jujutsu is no Git descendant (its command-line interface is shaped like Mercurial) and while familiarity is "great" for people coming from Git, the project shouldn't optimize for it.

I don’t think being used in Git is an argument against a name, though, if it’s better than the Mercurial name (and I don’t think being used in Mercurial is an argument for a name either, really). I think backout is a bad name.

Personally rollback makes me think of jj undo/jj op restore more than revert does.

Personally I haven’t heard a name I like better than revert and I think revert is just fine. I wouldn’t mind invert.

[PhilipMetzger]

n my opinion both backout and rollback are a more appropriate name for the command since Jujutsu is no Git descendant (its command-line interface is shaped like Mercurial) and while familiarity is "great" for people coming from Git, the project shouldn't optimize for it.

I don’t think being used in Git is an argument against a name, though, if it’s better than the Mercurial name (and I don’t think being used in Mercurial is an argument for a name either, really). I think backout is a bad name.

If it being used in Git is not an argument against it then it neither is one in favor of it. Since Jujutsu actually is something new, some unfamiliarity should be a given for users coming from Git, but that is not a bad thing.

[martinvonz]

I think I also like revert best (even though I'm the one who picked backout).

Is it worth coordinating a rename with the change in behavior we've talked about (#2802)? We could do it by adding revert with the new behavior and deprecating backout (without changing its behavior).

[zx8]

If it being used in Git is not an argument against it then it neither is one in favor of it. Since Jujutsu actually is something new, some unfamiliarity should be a given for users coming from Git, but that is not a bad thing.

@PhilipMetzger That's a reasonable assessment based on the OP. Re-reading my OP, I can see how it came across as "This is what is used ingit, so it makes sense to do the same in jj!" – but that wasn't my intention at all.

The reality is, I simply think "revert" is better terminology here, and is what I use in day-to-day parlance when speaking with colleagues, e.g. it feels natural to me to say to someone "Could you please revert yesterday's change?" but appreciate this could be a cultural difference.

[emilazy]

If it being used in Git is not an argument against it then it neither is one in favor of it. Since Jujutsu actually is something new, some unfamiliarity should be a given for users coming from Git, but that is not a bad thing.

I just think that either previous systems are irrelevant and we shouldn’t talk about them at all, or familiarity with Git can only, all else being equal, be a positive – perhaps a very mild positive, but not a negative, as long as the name is good on its own merits and the familiarity doesn’t lead to an inaccurate perception. If I thought git revert was a bad name I wouldn’t suggest it, but I think it’s better than hg backout, I can’t think of anything that seems strictly better, and so Git familiarity is just a cherry on top. “Git uses this name, so we shouldn’t, because we’re not Git” doesn’t make sense to me absent arguments that it’s not actually a good name.

Is it worth coordinating a rename with the change in behavior we've talked about (#2802)? We could do it by adding revert with the new behavior and deprecating backout (without changing its behavior).

If you mean making -d/-B/-A mandatory, I think that would be a sensible idea. I’m not sure I’m a fan of the original proposal in the issue.

[joyously]

I reread the help and it still seems like backout is similar to the concept of abandon. It has revset and destination options.
But the abandon help talks about rebasing descendants, and refers to similarity of restore. The help for restore refers to similarity of abandon.
If they are all different, the differences should be more apparent.

[PhilipMetzger]

@PhilipMetzger That's a reasonable assessment based on the OP. Re-reading my OP, I can see how it came across as "This is what is used ingit, so it makes sense to do the same in jj!" – but that wasn't my intention at all.

The reality is, I simply think "revert" is better terminology here, and is what I use in day-to-day parlance when speaking with colleagues, e.g. it feels natural to me to say to someone "Could you please revert yesterday's change?" but appreciate this could be a cultural difference.

Yes, and that presumably stems from Git's dominance since it is the thing you're used to (like when you say you merge a PR/MR, etc). In Mercurial-like systems it is natural to say "backout the Changeset ". See Saplings history for an example.

If it being used in Git is not an argument against it then it neither is one in favor of it. Since Jujutsu actually is something new, some unfamiliarity should be a given for users coming from Git, but that is not a bad thing.

I just think that either previous systems are irrelevant and we shouldn’t talk about them at all, or familiarity with Git can only, all else being equal, be a positive – perhaps a very mild positive, but not a negative

I disagree that it is not a negative, as it gives people the perception that Jujutsu just is another frontend for Git which may seem true now, but won't be in the future. It also carries all the baggage from Git's model with it.

If I thought git revert was a bad name I wouldn’t suggest it, but I think it’s better than hg backout, I can’t think of anything that seems strictly better, and so Git familiarity is just a cherry on top. “Git uses this name, so we shouldn’t, because we’re not Git” doesn’t make sense to me absent arguments that it’s not actually a good name.

I didn't say it was a bad name, it just carries a association which I deem to not favor us in the future. I prefer invert just to get that context away.

Is it worth coordinating a rename with the change in behavior we've talked about (#2802)?

SGTM

[zx8]

Since I'm conscious of this issue stagnating, and generally not a fan of leaving issues open indefinitely as they clutter up the issue tracker, do we have consensus on renaming to jj revert? This is also the kind of decision that should probably be made sooner rather than later; the longer people come to rely on something, the more friction it'll create when it's deprecated.

For me personally, since #5701 is now resolved, I don't mind whatever the final decision is.

[emilazy]

I remain in favour of revert (and I don’t think that using the same terminology as Git is inherently a negative, but if we’re penalizing terms for being used by other VCSes, then backout should get the same penalty and cancel it out). There are other options but I don’t think they’re strictly better; reverse sounds like it could be about commit ordering, invert is pretty nice (and is the other main contender in my eyes) but sounds to me kind of like it would change a commit in place rather than creating a new one. I think you could quibble that “revert” is usually used for returning to a previous state in its entirety rather than undoing one specific change, which might be the best argument against it.

If we can’t come to a consensus on the colour of the bikeshed then maybe we could ask the maintainer team to make a decision. I agree that stalling out is not ideal and that backout is bad.

[dbaynard]

@martinvonz Is it worth coordinating a rename with the change in behavior we've talked about (#2802)? We could do it by adding revert with the new behavior and deprecating backout (without changing its behavior).

[Emphasis added]

This sounds like a win-win? Especially if the new revert fixes an annoyance I have with backout (not printing the new change details). New behaviour without a breaking change, rename without a breaking change.

I like backout and think it is a better name than revert (I remember my initial confusion that git revert created a new commit rather than undoing the creation of my old one). Despite this, I favour the above proposal.

@joyously I reread the help and it still seems like backout is similar to the concept of abandon. It has revset and destination options.
But the abandon help talks about rebasing descendants, and refers to similarity of restore. The help for restore refers to similarity of abandon.
If they are all different, the differences should be more apparent.

This is an interesting point. Abandon and restore are (conceptually) inverses. Each is idempotent. Backout/revert is its own inverse (so actually invert has an algebraic accuracy).

Incidentally, I never really used git revert (mostly because I only really needed it to revert merges and I could never figure out the parent number business). I use jj backout all the time, mainly to handle changes that I intend to be temporary: merge the change and rebase the backout to ensure it remains a descendant of the trunk.

[emilazy]

FWIW, my main hesitation about jj invert is that I think Invert "Add really cool feature" is probably not super obvious as a commit message – the commit doesn’t itself invert the other commit, but rather is its inverse, and I don’t know how we could word it in a way that makes that clear. Conversely, I think “revert” works decently well in that context.

[martinvonz]

Feel free to send a PR for the rename. I think it would be even better if someone can find time to implement jj revert with suggested changes from #2802 (i.e. with a required-d/-A/-B, I think).

[emilazy]

(#5847 may help with that.)

[bnjmnt4n]

I'm happy to send a PR to add the -d/-A/-B arguments.

[PhilipMetzger]

If the majority wants revert then I apologize for my previously harsh tone. During the writing of the argument I also realized that revert is still the best name for it, as others just don't fit. So let's move on with the rename.