Repository: iterative/dvc

Issue:
term: replace (Git) "reference" for "revision" or "commit"
Revisions are slightly more accurate - https://git-scm.com/docs/revisions

> A revision parameter '<rev>' 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.


Comments:

Patch:
diff --git a/dvc/command/diff.py b/dvc/command/diff.py
--- a/dvc/command/diff.py
+++ b/dvc/command/diff.py
@@ -95,7 +95,7 @@ def _digest(checksum):
 
     def run(self):
         try:
-            diff = self.repo.diff(self.args.a_ref, self.args.b_ref)
+            diff = self.repo.diff(self.args.a_rev, self.args.b_rev)
 
             if not any(diff.values()):
                 return 0
@@ -131,20 +131,14 @@ def add_parser(subparsers, parent_parser):
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     diff_parser.add_argument(
-        "a_ref",
-        help=(
-            "Git reference to the older version to compare "
-            "(defaults to HEAD)"
-        ),
+        "a_rev",
+        help="Old Git commit to compare (defaults to HEAD)",
         nargs="?",
         default="HEAD",
     )
     diff_parser.add_argument(
-        "b_ref",
-        help=(
-            "Git reference to the newer version to compare "
-            "(defaults to the current workspace)"
-        ),
+        "b_rev",
+        help=("New Git commit to compare (defaults to the current workspace)"),
         nargs="?",
     )
     diff_parser.add_argument(
diff --git a/dvc/command/metrics.py b/dvc/command/metrics.py
--- a/dvc/command/metrics.py
+++ b/dvc/command/metrics.py
@@ -136,8 +136,8 @@ class CmdMetricsDiff(CmdBase):
     def run(self):
         try:
             diff = self.repo.metrics.diff(
-                a_ref=self.args.a_ref,
-                b_ref=self.args.b_ref,
+                a_rev=self.args.a_rev,
+                b_rev=self.args.b_rev,
                 targets=self.args.targets,
                 typ=self.args.type,
                 xpath=self.args.xpath,
@@ -283,20 +283,12 @@ def add_parser(subparsers, parent_parser):
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     metrics_diff_parser.add_argument(
-        "a_ref",
-        nargs="?",
-        help=(
-            "Git reference to the older version to compare "
-            "(defaults to HEAD)"
-        ),
+        "a_rev", nargs="?", help="Old Git commit to compare (defaults to HEAD)"
     )
     metrics_diff_parser.add_argument(
-        "b_ref",
+        "b_rev",
         nargs="?",
-        help=(
-            "Git reference to the newer version to compare "
-            "(defaults to the current workspace)"
-        ),
+        help=("New Git commit to compare (defaults to the current workspace)"),
     )
     metrics_diff_parser.add_argument(
         "--targets",
diff --git a/dvc/repo/diff.py b/dvc/repo/diff.py
--- a/dvc/repo/diff.py
+++ b/dvc/repo/diff.py
@@ -6,7 +6,7 @@
 
 
 @locked
-def diff(self, a_ref="HEAD", b_ref=None):
+def diff(self, a_rev="HEAD", b_rev=None):
     """
     By default, it compares the working tree with the last commit's tree.
 
@@ -47,8 +47,8 @@ def _paths_checksums():
         return result
 
     working_tree = self.tree
-    a_tree = self.scm.get_tree(a_ref)
-    b_tree = self.scm.get_tree(b_ref) if b_ref else working_tree
+    a_tree = self.scm.get_tree(a_rev)
+    b_tree = self.scm.get_tree(b_rev) if b_rev else working_tree
 
     try:
         self.tree = a_tree
diff --git a/dvc/repo/metrics/diff.py b/dvc/repo/metrics/diff.py
--- a/dvc/repo/metrics/diff.py
+++ b/dvc/repo/metrics/diff.py
@@ -83,9 +83,9 @@ def _get_metrics(repo, *args, rev=None, **kwargs):
         return {}
 
 
-def diff(repo, *args, a_ref=None, b_ref=None, **kwargs):
-    old = _get_metrics(repo, *args, **kwargs, rev=(a_ref or "HEAD"))
-    new = _get_metrics(repo, *args, **kwargs, rev=b_ref)
+def diff(repo, *args, a_rev=None, b_rev=None, **kwargs):
+    old = _get_metrics(repo, *args, **kwargs, rev=(a_rev or "HEAD"))
+    new = _get_metrics(repo, *args, **kwargs, rev=b_rev)
 
     paths = set(old.keys())
     paths.update(set(new.keys()))


Test patch:
diff --git a/tests/func/test_metrics.py b/tests/func/test_metrics.py
--- a/tests/func/test_metrics.py
+++ b/tests/func/test_metrics.py
@@ -890,7 +890,7 @@ def _gen(val):
     _gen("raw 2")
     _gen("raw 3")
 
-    assert dvc.metrics.diff(a_ref="HEAD~2") == {
+    assert dvc.metrics.diff(a_rev="HEAD~2") == {
         "metrics": {"": {"old": "raw 1", "new": "raw 3"}}
     }
 
@@ -916,7 +916,7 @@ def _gen(val):
     if not xpath:
         expected["m.json"]["a.b.e"] = {"old": "1", "new": "3"}
 
-    assert expected == dvc.metrics.diff(a_ref="HEAD~2")
+    assert expected == dvc.metrics.diff(a_rev="HEAD~2")
 
 
 def test_metrics_diff_broken_json(tmp_dir, scm, dvc):
@@ -939,4 +939,4 @@ def test_metrics_diff_broken_json(tmp_dir, scm, dvc):
 
 def test_metrics_diff_no_metrics(tmp_dir, scm, dvc):
     tmp_dir.scm_gen({"foo": "foo"}, commit="add foo")
-    assert dvc.metrics.diff(a_ref="HEAD~1") == {}
+    assert dvc.metrics.diff(a_rev="HEAD~1") == {}
diff --git a/tests/unit/command/test_metrics.py b/tests/unit/command/test_metrics.py
--- a/tests/unit/command/test_metrics.py
+++ b/tests/unit/command/test_metrics.py
@@ -30,8 +30,8 @@ def test_metrics_diff(dvc, mocker):
     m.assert_called_once_with(
         cmd.repo,
         targets=["target1", "target2"],
-        a_ref="HEAD~10",
-        b_ref="HEAD~1",
+        a_rev="HEAD~10",
+        b_rev="HEAD~1",
         typ="json",
         xpath="x.path",
         recursive=True,