jj-vcs
revset: add revision_id()
commit_id() is kept as an alias.
This is a subpart of consistently using "revision" instead of a mix of "commit" and "revision" in jj user interface.
Related to #7524
Checklist
If applicable:
- [ ] I have updated
CHANGELOG.md - [ ] I have updated the documentation (
README.md,docs/,demos/) - [ ] I have updated the config schema (
cli/src/config-schema.json) - [ ] I have added/updated tests to cover my changes
commit_id() is kept as an alias.
I don't think it is necessary to keep that symbol around forever but let's gather some feedback first. So could you add a TODO about potentially deprecating it in favor of revision_id at some point in the future.
My impression is that some users think "revision" and "change" are synonyms, so I wonder if this is going to confuse them. Perhaps it's a good way to teach them that "revision" isn't what they think it is.
My impression is that some users think "revision" and "change" are synonyms, so I wonder if this is going to confuse them.
I had this problem for a long time. Even figuring out that revision and commit were synonyms was confusing. I do think that using only one or the other is best, but commit is tied to Git and I don't know which of revision or commit is better for Piper. While revision makes sense because it's a noun, an actual synonym for change, and is the basis of revset, using it everywhere would seem to increase the misconception of revision and change being the same thing. Should revset be changeset?
I found the concept of "change" compelling from the start, possibly because of my past experience with Gerrit. The change-ids feature, in particular, was a key aspect that drew me to jj.
That said, the interchangeable use of the terms "commit" and "revision" was a source of early confusion. Before understanding they were synonyms, I was unclear on where this concept fit within the larger structure—was it a change, a commit, or something else entirely?
Many users transitioning from Git are familiar with the term "commit," but not necessarily with "change" or "revision." I wonder if it would be less confusing if the documentation and UI only used one term for a "revision," so that it's easier to see the difference between a "change" and a "revision"?
Should revset be changeset?
Revsets resolve to revisions/commit, not to changes, so I think that would be very confusing.
Revsets resolve to revisions/commit, not to changes, so I think that would be very confusing.
Everything resolves to revisions/commit, doesn't it? But the user types change IDs for the revset, although I think you can type a mixture, can't you? Where <REVSET> is used in the CLI Reference, it's mostly change IDs that you enter.
Everything resolves to revisions/commit, doesn't it?
Revsets resolve to revisions/commits, yes. Fileset resolve to file paths. We have talked about possibly adding "bookmark sets", which would resolve to bookmark names. I'm not trying to pick on your use of "everything" here. My point is instead that I think we should name the thing after what it resolves to, not after what it typically resolves from.
But the user types change IDs for the revset, although I think you can type a mixture, can't you?
Right, you can pass in change IDs, commit/revision IDs, bookmark names, revset aliases, or other kinds of symbols (e.g. custom ones).
To me, "revision" and "change" are high-level concepts, and "commit" is a lower-level representation of a revision or a change depending on context. My feeling is that a CommitId is lower-level thing, so commit_id() sounds better than revision_id().
@yuja could you describe how you understand "revision" and "change"? From the discussions on discord, I've seen many definitions for "revision"—it would be interesting to have your opinion on the subject.
I consider that "revision" is largely interchangeable with "commit" in the doc, but sounds more abstract term than "commit". There wouldn't be a "revision object", but a "commit object" can be referred to as a "revision". I personally don't use "change", but it seems natural to think that a "change" is a (set of / visible) revision/commit identified by a "change ID", and usually refers to a single revision/commit.
The idea here is to hide the term “commit” from the user in favor of “revision,” in order to avoid confusion introduced by the existence of two terms for commit/revision.
I think it would be strange for the documentation to say to use commit_id() to map the revision ID to a given prefix, or that a revision identifier is a commit-id.
And in my opinion, commit_id() should also remain (at least for backward compatibility reasons), but we shouldn't highlight it in the documentation.
And in my opinion,
commit_id()should also remain (at least for backward compatibility reasons), but we shouldn't highlight it in the documentation.
I think my ideal proposal for the deprecation of both the Commit and commit_id() symbol would them being around for roughly 18-24 months, similar to the jj merge/checkout removals.
Also I think you forgot to rename the Commit symbol in the template language here.