clean up the `help` a bit

[joyously]

Description

There are some inconsistencies in the help output.

1. The version command is so vague, and since this is "version control", it seems like it should not be showing the global options. I think it should self-reference the executable so it doesn't look like it's a version of the repo.

2. There are 4 uses of repo, (chmod, git, init, status), but this isn't helpful for those that need to use a translator to get the whole idea.

3. next and prev end with a period; the rest do not.

4. undo uses back ticks and refers to jj, which it probably should not.

5. Although the glossary says that revision is a synonym for commit, commit is both a verb and noun, and in jj the command is an alias. The noun commit is used 8 times in the command help, while revision is used 16 times. The white part is 80 columns. The glossary page has a table of contents, but it has commit 72 times and revision 6 times. Considering that "revset" (also not a word that will translate) is baked in, maybe revision should be the real thing and commit is the synonym.

6. I wonder if alphabetical listing of commands is the most useful. help is at the end though. It could be sorted by type of object affected or workflow (help and init at top) or basic CRUD order.

I just noticed that the contributing.md refers to checkout, which was removed, so this might be in other places also.

Specifications

• Version: 0.14.0

[PhilipMetzger]

3. next and prev end with a period; the rest do not.

This is probably my fault. I'll fix it when I have the time.

5. Although the glossary says that revision is a synonym for commit, commit is both a verb and noun, and in jj the command is an alias. The noun commit is used 8 times in the command help, while revision is used 16 times.

We had a inconclusive discussion about renaming commit to revision sometime ago, I clearly prefer revision but we should just a spelling.

5. The glossary page has a table of contents, but it has commit 72 times and revision 6 times. Considering that "revset" (also not a word that will translate) is baked in, maybe revision should be the real thing and commit is the synonym.

Agreed.

6. wonder if alphabetical listing of commands is the most useful. help is at the end though. It could be sorted by type of object affected or workflow (help and init at top) or basic CRUD order.

The help at the end stems from Clap, so I don't know if that is configurable. I'm sort of split on sorting it by workflow, but it could be a great idea.

[Jollywatt]

I think being consistent with the language of "revisions" instead of "commits" would be a key point for learners. I got quite hung up on that until I found the glossary!

"Revision": a set of changes; jj's equivalent of git's "commit"

"Commit" (verb): jj describe then jj new

"Commit" (noun): a git commit, not a jj revision

(I'm in love with jj by the way — I found it two days ago and I already know I'll never go back to git!)

[martinvonz]

I actually think of "revision" and "commit" (noun) as synonyms.

"Revision": a set of changes; jj's equivalent of git's "commit"

And here it sounds like you also do.

"Commit" (noun): a git commit, not a jj revision

But here it sounds like you don't. What nuance am I missing?

I think being consistent with the language of "revisions" instead of "commits" would be a key point for learners. I got quite hung up on that until I found the glossary!

Do you mean that it's confusing that we use both "revisions" and "commits" for the same thing? (Maybe the answer will be obvious based on you answer to my question above.)

[Jollywatt]

Do you mean that it's confusing that we use both "revisions" and "commits" for the same thing?

At least to me, it was confusing. All the words one tends to come across in version control ("commit", "move", "rebase", "revert", "reset", "split" "blame", …) tend to have very specific meanings, so I assumed that the word "revision" was carefully picked to denote something distinct from a "commit".

This is my mental model after two days of knowing about jj:

	Checkpoints in history	When editing a file	UX
jj	changes, change IDs	revisions are made	🤩
git	commits, commit IDs	index becomes dirty	😶

Notice that "commits" and "revisions" don't line up.

I understand that technically jj’s revisions are just git commits, but they are still semantically different. This was reinforced when I learned that jj’s "to commit" was only an alias for "describe then make new", so named to cater to git-knowers.

But here it sounds like you don't [think they’re synonymous]. What nuance am I missing?

I was meaning perhaps we should reserve the word "commit" (as a noun) for when talking about git’s commits (e.g., when explaining how jj’s revisions work with the git backend).

This is all subjective, but bottom line, I think eliminating synonymous jargon terms is good. Not necessarily across the entire documentation, but at least for one-line command descriptions.

[joyously]

Maybe the nuance is that in the English dictionary, commit is only a verb. The VCS world has made it into a noun. While jj currently uses a Git backend, the help text should be in jj terms, and not in the current backend's terms. So the alias commit is good for those used to Git, aligning revset with revision would be best.

[joyously]

This is my mental model after two days of knowing about jj

Rereading @Jollywatt 's reply, maybe he didn't get the right model since he seems to be saying that "revisions equals change" but also that "commits and revisions don't line up".

Jujutsu documentation says that the focus is on tracking "changes", which is good, and the decision not to use the ambiguous word "change" for a command or in the help text is very good (unlike Pijul-- that word is confusing). I think the subtlety of mixing implementation details in command output and explanations makes it harder to convey the "jj way" of doing things.

[Jollywatt]

maybe he didn't get the right model

Wait, what's not right about that model? o.o

[joyously]

Wait, what's not right about that model?

It's so subtle you can't see it from what I said? For jj, you used "revisions are made", which is correct but that also means "commits are made" since they are synonyms, and "there can be multiple revisions per jj change". If there were no Git backend, but a jj native backend, it would just be "changes".

[Jollywatt]

I think we are in fact on the same page. I'm just advocating for not having "revisions" and "commits" as synonyms. My reason is that, if they were synonymous, we'd have this:

	Checkpoints in history	When editing a file
jj	changes, change IDs	commits are made
git	commits	index becomes dirty

...which is a little confusing, because now "commit" refers to different concepts in the jj versus git mental model.

[joyously]

I don't think it's quite the same, since I'm advocating for keeping implementation details like the words "revisions" and "commit" out of the explanations entirely. But I do favor "revision" because it's a real noun that goes with "revision set" (revset) and "change", if one has to be mentioned. Edit: by the way, that table with only "commits" is correct. It's only confusing to you because your mental model is a little off.

[necauqua]

In my head revisions are things identified by change ids, and commits are things identified by commit ids.

Commits are immutable objects in the git content addressable store, every time we rewrite a revision/commit we actually create a new commit and hide the old one (and it's the absolute same in git, the whole point is that they're immutable) and the revision gets mutated.

We can list all commits that the revision has been with obslog. Every time a snapshot happens a new commit is created, the working copy revision is amended.

Basically git does have revisions - but they are only in your head, the commits you amend change yet they represent the same work, for which things like gerrit and jj added the change-id thing. And also git is branch-centric so usually you think of amending the feature-branch or something.

So "when edititng a file - revisions are made" sounds super-duper wrong to me (contrary to the "when edititng a file - commits are made", which I mean is literally what happens) :upside_down_face:

[joyously]

In my head revisions are things identified by change ids, and commits are things identified by commit ids.

That all sounds good, but doesn't match the glossary saying that they are synonyms.

[Jollywatt]

In my head revisions are things identified by change ids, and commits are things identified by commit ids.

This is why I think we should standardise. It's too easy to think "revisions" and "commits" are different.

Edit: I also originally thought this