Why use JJ: for comments

[ppwwyyxx]

When drafting commit messages, e.g. in jj describe or jj split, we are given a file where lines starting with JJ: are removed.

Although technically users can configure their editor to recognize .jjdescription file and then recognize JJ: as comment symbol, but that's extra work users have to do. Otherwise users don't get syntax highlighting.

My questions:

1. Why use JJ: instead of # to start comments? If using #, it's easier for users to configure their editor and adopt from git. For example, I can do au Bufread *.jjdescription set ft=gitcommit in vim.
2. Why use .jjdescription instead of, for example, .jj/repo/COMMIT_EDITMSG that is already recognized by editors?

I may be missing on the advantages of these choices, hence what I see now is just that they add extra burden for users coming from git.

[martinvonz]

I just copied that from Mercurial (see an example in https://www.mercurial-scm.org/guide#log_keeping). I don't think I thought much about using other syntax. I don't mind switching to #. Is it an issue that it's used in markdown? Even though markdown might be used frequently in commit messages, it's probably rare to include a level-1 heading?

[ilyagr]

My thinking was that if we keep JJ: for comments, we could have something like JJ_SEPARATOR: or JJ_DIRECTIVE: for separators. Perhaps we can come up with something better.

[martinvonz]

Whatever syntax we use, maybe the syntax should have a way of escaping the comments. Then we can produce the escaped form when we open the editor and not run into the lossy-roundtrip problem you ran into with git.

[ilyagr]

I'm getting more confused: apparently Git is supposed to be smarter about it and pick a different escape character if # is used in the message:

https://stackoverflow.com/a/14931661

I'm pretty sure I saw what I saw, but I'm not sure why. Perhaps the smart behavior requires some setting that jj git clone --colocate doesn't set, or became somehow customized on my system? Perhaps StackOverflow is wrong?

Update: According to git/git@84c9dc2, it seems you need to set a setting for the smart behavior. See also https://git-scm.com/docs/git-config#Documentation/git-config.txt-corecommentChar.

I'm not sure whether jj should set it by default in co-located repos (it could trigger confusion or some rarely seen bugs in Git).

Update 2: See also https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---cleanupltmodegt (this is duplicated in the next message in the thread)

[ilyagr]

One out-there possibility is to switch from JJ: to something like VCS: and try to convince hg/git to support that. For that, we'd have to design a clearly good approach. It's possible this would be also useful for more tools than VCS-es.

Off the top of my head, the best thought I have so far is to allow the following at the beginning of a line:

• VCS: starts a comment
• VCS LITERAL: is removed and the remainder of the line is left as is (this is the escaping).
• VCS SOMETHING_ELSE: is left for tools to interpret however they want. For example, jj describe with multiple commits could use something like VCS BEGIN: Description for commit XXX (do not change this line), where XXX is the relevant commit id. (Or we could only allow VCS BEGIN for now).

This could of course also work for JJ instead of VCS.

---

I also am not ruling out deciding that any of these options is not worth the trouble and switching to Git's approach, in spite of its Markdown limitations.

---

One more thing to look at is Git's "scissors" approach: https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---cleanupltmodegt.

[Dr-Emann]

Ah, I guess git's scissors mode is included automatically if you do git commit -v, which includes the full diff after # ------------------------ >8 ------------------------

And now I understand >8, it kinda looks like a pair of scissors.