term: replace (Git) "reference" for "revision" or "commit"

[ghost]

Revisions are slightly more accurate - https://git-scm.com/docs/revisions

A revision parameter '' typically, but not necessarily, names a commit object.

References are the ones living in .git/refs: https://git-scm.com/book/en/v2/Git-Internals-Git-References

We use the term references in metrics and diff commands, but both commands accept revisions, since repo.brancher accepts revs(not refs).

This change would also require updating the docs.

[jorgeorpinel]

From same discussion in #3244 (review), I think the conclusion is that the easiest thing to do is to use "commit" everywhere (same as the official reference for git diff does, for example, https://git-scm.com/docs/git-diff) instead of both "revision" and "reference", to avoid getting into Git's jargon too much.

• As a first step though, making everything "revision" like in our dvc get/import commands is also OK. Notice that "revision" means "Synonym for commit (the noun)" per https://git-scm.com/docs/gitglossary#def_revision

[jorgeorpinel]

p.s. using the more general term "version" instead of revision sometimes is also best. E.g. in the new dvc diff description by Ramón: "Compare two different versions of your DVC project (tracked by Git)" 👍

[jorgeorpinel]

Note: other Git terms we may want to review/avoid are:

• "working tree" in favor of "current workspace" or something like "local changes", as appropriate.
• Maybe "SHA" in favor of "commit hash"? (This is the route we're currently going in docs.)

[ghost]

I can agree on using commit instead of references or revisions, it is more well known and user-friendly.

"working tree" in favor of "current workspace" or something like "local changes", as appropriate.

👍 just to be clear, this specific case ("working tree" -> "current workspace") would apply only for the messages that users see, since it makes sense to talk about trees on the code.

Maybe "SHA" in favor of "commit hash"? (This is the route we're currently going in docs.)

the only instance of "commit hash" that I found on the code was on completion scripts, and it this case it makes more sense to use only commit:

dvc/scripts/completion/dvc.zsh

Line 142 in 8787ac0

"--rev[DVC repository git revision.]:Commit hash:"

[jorgeorpinel]

it makes sense to talk about trees on the code

Any time a more precise Git term is available in code var/fn names, coments, docstrings, debug output, etc. it should definitely be used, I think. But yes, for user-facing stings we want to simplify terminology and avoid Git jargon as much as possible – hopefully completely.

the only instance of "commit hash"...

OK cool that's easy then. We should prob also look for just "hash" which depending on the context may refer to a commit SHA. Thanks

[jorgeorpinel]

p.s. I'm down to take this issue as well as other terminology reviews in the code base (e.g. avoid "checksum") but won't have time for it very soon. Maybe next week if I don't keep track of it...

[ghost]

OK cool that's easy then. We should prob also look for just "hash" which depending on the context may refer to a commit SHA. Thanks

Looks like we don't use hash at all 😅

[jorgeorpinel]

Term "revision" still exists in

dvc/dvc/command/imp.py

Line 54 in 7821fa6

"--rev", nargs="?", help="Git revision (e.g. SHA, branch, tag)"

dvc/dvc/command/get.py

Line 72 in 7821fa6

"--rev", nargs="?", help="Git revision (e.g. SHA, branch, tag)"

dvc/dvc/scm/git/tree.py

Line 105 in de1f67a

"revision '{}' not found in Git '{}'".format(

dvc/dvc/scm/git/__init__.py

Line 90 in e7b3297

"failed to access revision '{}' for repo '{}'".format(

and maybe

dvc/tests/func/test_diff.py

Line 110 in fd1e6f4

with pytest.raises(DvcException, match=r"unknown Git revision 'missing'"):

as well as corresponding changes in dvc/scripts/completion/dvc.zsh

besides docstrings, comments, and code, of course – but not expecting those to change right now necessarily (per #3299 (comment))

[efiop]

@jorgeorpinel revision sounds better than commit when applied to API/CLI, as --commit sounds like some sort of action. revision sounds the best to me over all other alternatives, tbh.

[jorgeorpinel]

Git "revision" means "Synonym for commit (the noun)" per https://git-scm.com/docs/gitglossary#def_revision.

Using the more general term "version" instead of revision when possible is also best. E.g. in the new dvc diff description by Ramón: "Compare two different versions of your DVC project (tracked by Git)" – this is the current approach in docs.

[shcheklein]

It would look strange and not right to me as an option --commit. It'll be confusing for DVC.

[efiop]

@jorgeorpinel I have no problem with "Compare two different versions" in the docs or any explanations, but version when applied to CLI/API sounds like a tag to me (just based on what first comes to my mind when I hear it), while revision is a more general term (again, IMPO), so I don't really see any point in changing rev that we currently have to it.

[jorgeorpinel]

I have nothing agains the term "revision". Originally I argued it feels more correct than commit in fact (it encompasses branches, tags, etc, not just a commit SHA) but I thought that per some other discussion with Ivan (not in this issue) we had concluded that its best to always use "commit" for simplicity and not to get into Git terminology. But I guess that's not the case? I'm more than happy to keep using "revision"!

Just curious about the instances in dvc/dvc/scm/git/tree.py and dvc/dvc/scm/git/__init__.py I mentioned in #3245 (comment) above. Otherwise, this is closable for me.