Rename edit to something that better convey what it actually does

[kuchta]

edit is a bit unfamiliar term in the context of VSC and could imply some data/history modifications (which it doesn't do by itself), so using either switch or checkout would be probably easier to get for newcommers (like me 😀) and better convey the fact that it just switches WC like the prev and next commands (with -e parameter).

[bnjmnt4n]

The difference between switch/checkout (in a Git sense) and jj edit is that once you've set the given change as your new working copy, any changes to the working directory will amend the working copy commit. Hence, I feel like it's clearer that you are editing a change, whereas switching or checking out a change doesn't imply the same thing (that the change will actually be modified when your working directory changes).

[kuchta]

Well, interpretation of anything depends on the fundamentals, or first principles and editing current (WC) commit is IMHO default mode of operation of JJ. That's probably the first thing anybody would learn that editing files in WC changes WC commit (and rebases it's possible descendants) and through this understanding they would try to interpret anything new...

[thoughtpolice]

Note that we have a jj checkout command — which is just a specialized form of jj new — and it was deprecated this year in order to nudge people to use jj new instead, as it has a superset of functionality — but also because having redundant verbs for the same action seems less than ideal in general and is something we try to avoid to reduce confusion in the long run. A big problem with git is that it has too many "verbs" and many of these have overlap or only work in specific cases in non-obvious ways. We want to avoid that.

I'm rather we not bring it back with some totally different-but-somewhat-similar behavior; jj new and jj edit are not the same thing, but between the two, I think jj new is the better one for checkout to be a duplicate of, because jj new creates a new working copy, much like how people expect checkout to work — git checkout "checks you out" to the exact state of some commit, and then your changes you make exist on top of that. jj edit fundamentally modifies the state of a commit itself, which is not the same thing at all.

Realistically, checkout is just as much of a strange term as edit is, arguably moreso. Edit literally means "Edit a commit." New means "create new commit on top of another commit." Checkout was originally a term coined in the RCS era to describe the fact that there was a server and only one client (user) was allowed to edit a file at a time. Therefore, when a programmer edited a file, it needed to be "checked out", which granted exclusive access, in the same way that a library book checked out by one person cannot be used by another person. CVS and others like SVN (maybe Arch?) inherited this term to mean "check out version X of a thing at a path", which is a kind of vaguely similar concept but not really the same as the library book concept because there was no exclusive locking.

Again, it's all a bit moot, because I'd rather we stick to our guns, actually deprecate it, and eventually remove it entirely from the default UX. Assuming we do this, then it can become an alias for whatever you want, too. This is really much better in the long run because some people have other ideas for how checkout should behave; we've had requests for it to be equivalent to jj rebase -s @ -d $TARGET for example, which would "bring your working copy along with you", which is exactly how git checkout behaves.

I do not think there is one, consistent interpretation of "checkout" that actually makes 100% sense and is perfectly analogous to how Git works, which in practice is what people want us to do for things like this. Much of the default "working flows" in Jujutsu are fundamentally different enough from Git that I don't think checkout is worth keeping around; it's an extremely minor bump but very unlikely to be the biggest roadblock. And we try to avoid "over-indexing" on Git's view of the world, because it constrains our design space. I'd rather we not change checkout at all, and instead not endorse it at all.

[kuchta]

I'm definitely not trying to bring ilogical git nomenclature here, on the contrary. If people percieve checkout in such burdened way, than I'm for using switch (or something totally new), which is probably not so much loaded. The thing is, any newcommer will soon realize that editing WC commit is it's default mode of operation and it's distinguishing feature, so calling something edit if it's the default just seems not very consistent with it's philosophy. It may be I'm not getting it's philosophy right, but what is it then? It must have some to let people know how to interpret it's operations (nomenclature) if it doesn't want to become next ilogical git-like non-sense. I understand that you can perceive such switching operations as more dangerous, but nothing is more dangerous than doing something you don't know how to use/interpret and simple consistent philosophy/methodology can make that more clear and so even paradoxically more safe....

[thoughtpolice]

I think switch would fall into the same category that checkout does in the first point: it introduces redundant verbs that are just special forms of other, more general verbs. I am largely against doing this unless the term is exceedingly common; jj commit is an example of where I don't complain about the redundant behavior, for instance, since it's an incredibly common shorthand.

I'm admit I'm not so sure I follow you. In my view, Jujutsu is defined by the fact that most operations, in a broad sense, work on the commit graph, not on the "working copy", and almost everything is a commit in the graph. Including the working copy — it is just a specific commit in the graph, one that is updated automatically, but not much more than that. So, this worldview means you create new nodes in the graph (jj new), edit the content in existing nodes (jj edit), change the message attached to a node in the graph (jj describe), move things between nodes (jj squash --from ... --into ...) or even change the relationships in the graph entirely by changing the edges between nodes (jj rebase, which could arguably be called "reparent"). Most of these commands don't do anything special for "the working copy", because it's only a commit, like any other (except in some special cases where they need to update the filesystem, for example rebasing a parent of the working copy, which needs to be reflected by updating files in the filesystem.)

I think a hidden part of your complaint might be more along the lines of, "what is the right conceptual workflow for Jujutsu", i.e. when do I do new versus edit? How do I manage my work as I evolve it? Broadly speaking most everyone falls into two camps, "squash workflow" or "edit workflow." These are described here:

• https://steveklabnik.github.io/jujutsu-tutorial/real-world-workflows/the-squash-workflow.html
• https://steveklabnik.github.io/jujutsu-tutorial/real-world-workflows/the-edit-workflow.html

(BTW, this tutorial/guide is pretty good and IMO much better than our own which is somewhat dated, so if you're a new user and you haven't seen it, you might enjoy reading it!)

Most of us use the "squash" workflow. So in this case I don't actually see "edit" as the "default" as you suggest; rather it's the other way around. About 90% of the time, I use jj new, and then update the graph by using jj squash to move my changes somewhere else. The other 10%, I might jj edit a commit directly, often when I pick up work I previously left in some very incomplete state.

So, I think a big part of the problem isn't so much the actual name of the command (again, I think edit is much more accurate as to its behavior than switch or checkout are.) Rather, it's making sure people have a solid understanding of where these go in the toolbox and their semantic meaning.

[kuchta]

@thoughtpolice Yes, I think you don't follow me, because you are basically stating the same philosophy that I mentioned, that upon change JJ is changing WC commit AND it's descendents (as I mentioned in previos comment) as you call commit graph. So if anybody anyhow "switches" to any commit they should know what it could cause and be cautios. IMHO making up for that by changing logical defaults to illogical ones doesn't bring more safety, just more confusion and so more danger...

BTW, thank you for the tutorial, that's exactly what I've discovered yesterday and you are right, it's much better than the official one, so it would be great to be mentioned there....

[joyously]

It creates a new commit.

I would have said a new "change", but under the covers that's a new commit.
And I also don't see any reason to rename a clear verb to a vague verb.

[joyously]

I would agree that new is not a verb, so it's a little questionable. But I think it's short, and clear that it makes a new thing.
I am still in a beginner's mind with jj, but I don't have a Git background. commit is not a specific term to me and it is not clear what it does. edit is very clear that an existing thing will be changed.
Beginners read the help text, and that does explain the commands, so I think your argument about knowing what the commands do from the name of the command is pretty weak.
The commands don't dictate the "default mode of operation". That is in the choice of default values for the options, and which commands the user chooses.

[kuchta]

@joyously No, commands themselfs don't dictate default mode of operation, that is something people will extract from the workings of the system. There is probably no point in commenting on the rest 🙂

[ilyagr]

I would agree that new is not a verb

From this perspective, jj create would make more sense.

In my mind, though, new is such a common command that a short word is an advantage. OTOH, jj create with an alias new might make sense. (I don't know if it's a huge improvement over the status-quo though).

[kuchta]

Well, I suppose when we take it that the main function of this system is creating versions/changes/commits, so probably even such general terms like new is probaby acceptable. create is probably better, but I'm still for a term that describe what would be it's result. commit is probably too snapshot based and since modeling conflicts needs to some notion of a change so change may be even better. The main problem I have with current commit is that it's workflow specific command that should probably be just as alias or more precisely user defined configuration function, but I'm quite againt including such functions in the default installation without user consent. Probably the best way would be to provide the user with predefined sets of such functions targeted at specific workflows that the user can then change themselves if they wish to do so.

[thoughtpolice]

The note about danger/chaos maybe helps me understand you a bit more, but I'm afraid I don't see how "switch" is any more explanatory than "edit" in your scenario, or how it makes any kind of danger to the user any more obvious. Actually, I can see how it might be seen as "dangerous" from a Git POV, but the only reason people think switch is dangerous in my experience is because in Git:

• git checkout in a dirty working copy can fail, because of a potential conflict with the working copy and the place you want to move to, which means you either need to throw away your working copy or stash it. It might amaze you how many times people lose work to this.
• Detached HEAD states cannot easily be recovered, which is why Git prints a scary message. It's very difficult to rediscover these if you lose them, and very scary if you think you lost work.
• Conflicts from editing previous commits in a chain can often result in extremely tedious rebases, and rebases are a prime way to lose work. Example: you git rebase a change, and have a conflict, you need to git add and then git rebase --continue to move onto rebasing the next commit. However, an extremely common mistake is to do git add and then git commit instead. This will succeed, despite the fact you have not finished your rebase, and people begin to panic at this point and often try to back out the rebase completely, which throws away all the work they did to resolve the conflict in the first place. I've seen many people do this and then swear off git rebase forever.

In other words, moving the HEAD in Git is fundamentally an operation that can lose your work, and people find creative ways to do so, repeatedly. But none of these are nearly as dangerous in Jujutsu:

• jj new or jj edit will retain your old work, so you can always get it back. There is never a need to stash or clean your changes. They are always retained in the graph, and you can return to them.
• Detached HEADs are the default, and it is easy to see them in the commit graph, so you will not lose work by moving around. The graph is the source of truth.
• Conflicts are first class and recorded in a commit itself. This means if you do something like a rebase that goes wrong, you can either undo it (by undoing the rebase) or resolve the conflict in a number of ways without throwing away work. Importantly, a botched rebase like the example I outlined is nearly impossible, and you will not lose any work or be put into a bad state by incomplete resolutions.

But most importantly:

• You can jj undo nearly any operation, and all commands and their modifications to the graph are shown by jj op log. This makes editing the commit graph vastly safer than it is in Git, and this is important in order to assure the user that they can experiment without consequence. It is also a fundamental component of the design.
• You can see how any change has evolved using jj obslog (now that name I agree is not particularly great or obvious!) so you can exactly see what changes you made to the commit in question, at every step.

These points mean that not only is editing the graph easy, it is also often safer and more reliable than in alternative systems. These are fundamental design decisions that, when taken together, mean that a workflow that is dangerous in Git is safe and even preferable in Jujutsu.

---

But let's step back to the point you brought up; "it can cause chaos." If this is the crux of the matter it may come down to fundamental disagreement. In this case, I believe the problem is not the name of the command, but the very dangerous operation itself. You cannot stop people from doing dangerous things by expecting them to infer the level of danger from the name alone, and then stopping themselves. Many Git users have very poor understanding of how Git works anyway; in my experience they think of everything as dangerous (they just want to get their work done and never used advanced tools) or they think of nothing as dangerous (they delete their own work on accident), and relatively few people have good strong control over the tools to understand all the cases. Even then, they make mistakes. The level of danger that might be implied by a name is not really relevant in my mind; if the user is experienced, they know what it does, but if not, they tend to have simpler understandings, to the point where the name alone cannot capture all the possible dangerous results that they might land in.

Expecting the danger to be self-evident by some means — way of analogy ("switch is dangerous in Git, therefore it is dangerous here too"), or something else — is, frankly, a losing battle. This actually is a discussion that goes beyond switch vs edit; it is a more general principle of design.

Rather, if there are dangerous scenarios that can appear for a user, resulting in cases where they can make irrevocable mistakes — we should either make these scenarios impossible by design (rebase example above is nearly impossible in jj), or mitigate the outcome by providing safety measures like undo and op log to turn irrevocable mistakes into recoverable cases.

There are some scenarios that can make jj edit a bit "annoying" that I can think of, for example. However, I do not believe any of these cases would benefit from calling it switch; they have nearly no impact conceptual framework for the user. That would imply they would be able to foresee these outcomes just from the name of the command, despite being unfamiliar with them; but they are effectively so different in nature from what you would do in Git that I don't think that is reasonably the case. I also don't see how edit is particularly "illogical" compared to switch given the above framework. What are you editing? A commit in the graph! And editing a commit means the changes are seen by the descendents too. This isn't a particularly huge leap I think, in terms of concepts to learn.

[kuchta]

@martinvonz switch current WCC (and implicitly the WC) with the one you "go" to. But if you consider implementing user defined functions/aliases, then it's probably better to choose something not used by any commonly known workflow like the mentioned go-to...

[bnjmnt4n]

To me, it seems like the clearest name (which doesn't imply editing, or could cause confusion due to similarities to Git/other VCSes) would be something like set-working-copy.

[joyously]

something like set-working-copy

That makes sense, and looks similar to the global option --ignore-working-copy, but is too long.
Maybe the mental model is more like the graph sort of being the directory structure of the file system, as there is a current directory (.) and you can cd to other directories. (I don't like how this introduces the word "change".) By the way, is there any way in jj to not have a current working copy commit?

[martinvonz]

By the way, is there any way in jj to not have a current working copy commit?

Yes, you can jj workspace forget [<workspace id>] to remove the workspace from the repo (operation log). The files in your working copy won't be affected, they will just no longer be snapshotted and will not be updated when you rewrite commits.

[kuchta]

@joyously That's exactly how I thought about that recently. As a navigation in the FS...🙌🏻

[kuchta]

@martinvonz I believe you answered those questions honestly, but it's hard to answer them with the beginner's mind, if you are not in that state. new is a general term. If you don't know the system, you can't know what new could mean. commit on the other hand is specific term, so it's quite clear what it does and edit actually doesn't do any editing by itself, it just changes WC so it should convey that fact. Maybe the user doesn't want to edit anything, maybe he just wants to view (check out) a project at particular revision or he might want to perform some other operation relative to that commit (as WC), who knows... Yes, that WC (commit and it's descendants) could be potentially changed by any editing made to the filesystem, but that doesn't have to be the user's intent and even if it would as I already stated, that's the default mode of operation, that JJ upon changes to FS automatically commits WC and rebases it's descendents, so there's no need to convey that in a command that by itself doesn't change/commit anything apart from moving/switching/checking out (whatever you want to call it) the same way as prev/next probably shouldn't do. It's a super powerfull feature, to be able move around the commit graph and being able to actually change it just be making modifications to FS and with good nomenclature (and defaults) even super easy to discover. That's why I advocate it so much. Not everybody goes through tutorials and documentation, somebody learn by trying things out and the faster they understand it, the more likely they will use it...

[bnjmnt4n]

it's hard to answer them with the beginner's mind, if you are not in that state. new is a general term. If you don't know the system, you can't know what new could mean. commit on the other hand is specific term, so it's quite clear what it does

I guess that depends on what you consider a beginner. If you're a beginner to VCS, there's no reason to be clear what "commit" does.

edit actually doesn't do any editing by itself, it just changes WC so it should convey that fact. Maybe the user doesn't want to edit anything, maybe he just wants to view (check out) a project at particular revision or he might want to perform some other operation relative to that commit

I would agree with your argument that jj edit doesn't necessarily need to be called edit; it just "goes to" a commit, and as you mention it can cause the commit to be edited since all working directory modifications will modify the working copy commit. (However, I think a reason against calling it switch/checkout is that it can cause confusion when compared to the alternative VCS implementations of such a command.)

there's no need to convey that in a command that by itself doesn't change/commit anything apart from moving/switching/checking out (whatever you want to call it)

I think in the end it comes down to intention and workflow: does Jujutsu want to recommend a workflow where users "go" to a given commit and unintentionally modify it without realizing what they did? Or does Jujutsu want to make it intentional that "going" to a commit can edit the commit, by making the user call jj edit X? This might affect what we want jj next/prev to do as well.

(Personally, I would prefer to keep the jj edit name, without a better alternative.)

It's a super powerfull feature, to be able move around the commit graph and being able to actually change it just be making modifications to FS and with good nomenclature (and defaults) even super easy to discover. That's why I advocate it so much. Not everybody goes through tutorials and documentation, somebody learn by trying things out and the faster they understand it, the more likely they will use it...

This is true for both sides? Whatever the command is called, the user can still determine the behavior.

[kuchta]

1. I'm not advocating for any particular name, I'm quite fine with anything like go, switch, checkout that does convey what it does.
2. There are so many workflows (and rightly so, because it fullfils so many use-cases) and the tool that makes most of them possible (most general one) and easy to use (without pushing user to it's own) will probably win in the end, since this field have a tendency for convergence...
3. The user MAY determine it's behavior, if it's not very complex and/or inconsistent one (like git), in which case a lot of users just give up and use search engine/Stack Overflow/AI for unusual operations as is often the case

[kuchta]

@bnjmnt4n I was also thinking about something like set-working-copy but unfortunately it's quite long for such common command, but it could be probably solved by an alias like swc
Or maybe even better change-working-copy/cwc to make it more clear to anyone familiar with cd (change directory) which is IMHO shell counterpart and since cd also don't mention "working" directory then maybe just change-commit/cc would do...

[steveklabnik]

My two cents: jj edit makes so much sense to me, I've caught myself trying to use jj e a few times, and having that fail, ha!

[ilyagr]

You can add aliases.e=["edit"] to your config! Also aliases.n=["new"].