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

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.)

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:

https://github.com/iterative/dvc/blob/8787ac03808fcf38dcac01f7a57f82f216b28e12/scripts/completion/dvc.zsh#L142

[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