Merge pull request #3244 from jorgeorpinel/master

diff/metics diff: update argument descriptions, et al.

.github/PULL_REQUEST_TEMPLATE.md

@@ -5,4 +5,3 @@
 * [ ] ❌ Have you checked DeepSource, CodeClimate, and other sanity checks below? We consider their findings recommendatory and don't expect everything to be addressed. Please review them carefully and fix those that actually improve code or fix bugs.
 
 Thank you for the contribution - we'll try to review it as soon as possible. 🙏
-

debian/changelog

@@ -2,4 +2,4 @@ dvc (0.75.b1) experimental; urgency=low
 
   * First native Debian package version.
 
- -- Dmitry Petrov <dmitry@dataversioncontrol.com>  Sat, 07 Dec 2019 09:49:28 +0300
+ -- Dmitry Petrov <dmitry@dvc.org>  Sat, 07 Dec 2019 09:49:28 +0300

debian/control

@@ -1,5 +1,5 @@
 Source: dvc
-Maintainer: Dmitry Petrov <dmitry@dataversioncontrol.com>
+Maintainer: Dmitry Petrov <dmitry@dvc.org>
 Section: python
 Priority: optional
 Build-Depends: dh-python, python3-setuptools, python3-all, debhelper (>= 9)

debian/copyright

@@ -1,10 +1,10 @@
 Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
 Upstream-Name: DVC
-Upstream-Contact: Dmitry Petrov <dmitry@dataversioncontrol.com>
+Upstream-Contact: Dmitry Petrov <dmitry@dvc.org>
 Source: https://github.com/iterative/dvc
 
 Files: *
-Copyright: Dmitry Petrov <dmitry@dataversioncontrol.com>
+Copyright: Dmitry Petrov <dmitry@dvc.org>
 License: Apache 2.0
  On Debian systems, the full text of the Apache 2.0
  License can be found in the file

dvc/cli.py

@@ -91,7 +91,7 @@ class DvcParser(argparse.ArgumentParser):
 
 class VersionAction(argparse.Action):  # pragma: no cover
     # pylint: disable=too-few-public-methods
-    """Shows dvc version and exits."""
+    """Shows DVC version and exits."""
 
     def __call__(self, parser, namespace, values, option_string=None):
         from dvc import __version__

dvc/command/commit.py

@@ -47,7 +47,7 @@ def add_parser(subparsers, parent_parser):
         "--force",
         action="store_true",
         default=False,
-        help="Commit even if checksums for dependencies/outputs changed.",
+        help="Commit even if hash value for dependencies/outputs changed.",
     )
     commit_parser.add_argument(
         "-d",

dvc/command/diff.py

@@ -120,9 +120,8 @@ class CmdDiff(CmdBase):
 
 def add_parser(subparsers, parent_parser):
     DIFF_DESCRIPTION = (
-        "Compare two different versions of your DVC project (tracked by Git)"
-        " and shows a list of paths grouped in the following categories:"
-        " added, modified, or deleted."
+        "Compare two versions of the DVC repository.\n"
+        "Shows the list of paths added, modified, or deleted"
     )
     diff_parser = subparsers.add_parser(
         "diff",
@@ -134,8 +133,8 @@ def add_parser(subparsers, parent_parser):
     diff_parser.add_argument(
         "a_ref",
         help=(
-            "Git reference to the old version that you want to compare"
-            " (defaults to HEAD)"
+            "Git reference to the older version to compare "
+            "(defaults to HEAD)"
         ),
         nargs="?",
         default="HEAD",
@@ -143,8 +142,8 @@ def add_parser(subparsers, parent_parser):
     diff_parser.add_argument(
         "b_ref",
         help=(
-            "Git reference to the new version that you want to compare."
-            " (defaults to the working tree)"
+            "Git reference to the newer version to compare "
+            "(defaults to the current workspace)"
         ),
         nargs="?",
     )
@@ -156,7 +155,7 @@ def add_parser(subparsers, parent_parser):
     )
     diff_parser.add_argument(
         "--checksums",
-        help="Display checksums for each entry",
+        help="Display hash value for each entry",
         action="store_true",
         default=False,
     )

dvc/command/gc.py

@@ -52,10 +52,10 @@ class CmdGC(CmdBase):
 
 
 def add_parser(subparsers, parent_parser):
-    GC_HELP = "Collect unused data from DVC cache or a remote storage."
+    GC_HELP = "Garbage collect unused objects from cache or remote storage."
     GC_DESCRIPTION = (
-        "Deletes all files in the cache or a remote which are not in\n"
-        "use by the specified git references (defaults to just HEAD)."
+        "Removes all files in the cache or a remote which are not in\n"
+        "use by the specified Git revisions (defaults to just HEAD)."
     )
     gc_parser = subparsers.add_parser(
         "gc",

dvc/command/get.py

@@ -73,7 +73,7 @@ def add_parser(subparsers, parent_parser):
         "-o", "--out", nargs="?", help="Destination path to download files to"
     )
     get_parser.add_argument(
-        "--rev", nargs="?", help="Git revision (e.g. branch, tag, SHA)"
+        "--rev", nargs="?", help="Git revision (e.g. SHA, branch, tag)"
     )
     get_parser.add_argument(
         "--show-url",

dvc/command/imp.py

@@ -53,6 +53,6 @@ def add_parser(subparsers, parent_parser):
         "-o", "--out", nargs="?", help="Destination path to download files to"
     )
     import_parser.add_argument(
-        "--rev", nargs="?", help="Git revision (e.g. branch, tag, SHA)"
+        "--rev", nargs="?", help="Git revision (e.g. SHA, branch, tag)"
     )
     import_parser.set_defaults(func=CmdImport)

dvc/command/metrics.py

@@ -273,7 +273,8 @@ def add_parser(subparsers, parent_parser):
     metrics_remove_parser.add_argument("path", help="Path to a metric file.")
     metrics_remove_parser.set_defaults(func=CmdMetricsRemove)
 
-    METRICS_DIFF_HELP = "Output metric values."
+    METRICS_DIFF_HELP = "Show a table of changes between metrics among "
+    "versions of the DVC repository."
     metrics_diff_parser = metrics_subparsers.add_parser(
         "diff",
         parents=[parent_parser],
@@ -285,16 +286,16 @@ def add_parser(subparsers, parent_parser):
         "a_ref",
         nargs="?",
         help=(
-            "Git reference from which diff is calculated. "
-            "If omitted `HEAD`(latest commit) is used."
+            "Git reference to the older version to compare "
+            "(defaults to HEAD)"
         ),
     )
     metrics_diff_parser.add_argument(
         "b_ref",
         nargs="?",
         help=(
-            "Git reference to which diff is calculated. "
-            "If omitted current working tree is used."
+            "Git reference to the newer version to compare "
+            "(defaults to the current workspace)"
         ),
     )
     metrics_diff_parser.add_argument(

dvc/output/base.py

@@ -412,7 +412,7 @@ class OutputBase(object):
         if not self.info:
             logger.warning(
                 "Output '{}'({}) is missing version info. Cache for it will "
-                "not be collected. Use dvc repro to get your pipeline up to "
+                "not be collected. Use `dvc repro` to get your pipeline up to "
                 "date.".format(self, self.stage)
             )
             return NamedCache()

dvc/remote/base.py

@@ -66,7 +66,7 @@ class RemoteMissingDepsError(DvcException):
 class DirCacheError(DvcException):
     def __init__(self, checksum):
         super().__init__(
-            "Failed to load dir cache for checksum: '{}'.".format(checksum)
+            "Failed to load dir cache for hash value: '{}'.".format(checksum)
         )
 
 
@@ -191,7 +191,7 @@ class RemoteBASE(object):
                 tasks,
                 total=len(file_infos),
                 unit="md5",
-                desc="Computing hashes (only done once)",
+                desc="Computing file/dir hashes (only done once)",
             ) as tasks:
                 checksums = dict(zip(file_infos, tasks))
         return checksums
@@ -342,13 +342,13 @@ class RemoteBASE(object):
 
         A file is considered changed if:
             - It doesn't exist on the working directory (was unlinked)
-            - Checksum is not computed (saving a new file)
-            - The checkusm stored in the State is different from the given one
+            - Hash value is not computed (saving a new file)
+            - The hash value stored is different from the given one
             - There's no file in the cache
 
         Args:
             path_info: dict with path information.
-            checksum: expected checksum for this data.
+            checksum: expected hash value for this data.
 
         Returns:
             bool: True if data has changed, False otherwise.
@@ -364,7 +364,7 @@ class RemoteBASE(object):
 
         checksum = checksum_info.get(self.PARAM_CHECKSUM)
         if checksum is None:
-            logger.debug("checksum for '{}' is missing.", path_info)
+            logger.debug("hash value for '{}' is missing.", path_info)
             return True
 
         if self.changed_cache(checksum):
@@ -376,7 +376,7 @@ class RemoteBASE(object):
         actual = self.get_checksum(path_info)
         if checksum != actual:
             logger.debug(
-                "checksum '{}'(actual '{}') for '{}' has changed.",
+                "hash value '{}' for '{}' has changed (actual '{}').",
                 checksum,
                 actual,
                 path_info,
@@ -962,7 +962,7 @@ class RemoteBASE(object):
         skip = False
         if not checksum:
             logger.warning(
-                "No checksum info found for '{}'. " "It won't be created.",
+                "No file hash info found for '{}'. " "It won't be created.",
                 path_info,
             )
             self.safe_remove(path_info, force=force)

dvc/scm/git/tree.py

@@ -102,7 +102,7 @@ class GitTree(BaseTree):
             tree = self.git.tree(self.rev)
         except git.exc.BadName as exc:
             raise DvcException(
-                "revision '{}' not found in git '{}'".format(
+                "revision '{}' not found in Git '{}'".format(
                     self.rev, os.path.relpath(self.git.working_dir)
                 )
             ) from exc

dvc/state.py

@@ -23,13 +23,13 @@ logger = logging.getLogger(__name__)
 
 
 class StateVersionTooNewError(DvcException):
-    """Thrown when dvc version is older than the state database version."""
+    """Thrown when DVC version is older than the state database version."""
 
     def __init__(self, dvc_version, expected, actual):
         super().__init__(
-            "you are using an old version '{dvc_version}' of dvc that is "
-            "using state file version '{expected}' which is not compatible "
-            "with the state file version '{actual}' that is used in this "
+            "you are using an old version '{dvc_version}' of DVC that is "
+            "using state file version '{expected}', which is not compatible "
+            "with the state file version '{actual}', that is used in this "
             "repo. Please upgrade right now!".format(
                 dvc_version=dvc_version, expected=expected, actual=actual
             )

dvc/version.py

@@ -11,7 +11,7 @@ _BASE_VERSION = "0.82.8"
 
 
 def _generate_version(base_version):
-    """Generate a version with information about the git repository"""
+    """Generate a version with information about the Git repository."""
     pkg_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 
     if not _is_git_repo(pkg_dir) or not _have_git():
@@ -28,7 +28,7 @@ def _generate_version(base_version):
 
 
 def _is_git_repo(dir_path):
-    """Is the given directory version-controlled with git?"""
+    """Is the given directory version-controlled with Git?"""
     return os.path.exists(os.path.join(dir_path, ".git"))
 
 
@@ -57,7 +57,7 @@ def _is_release(dir_path, base_version):
 
 
 def _git_revision(dir_path):
-    """Get the SHA-1 of the HEAD of a git repository."""
+    """Get SHA of the HEAD of a Git repository."""
     return subprocess.check_output(
         ["git", "rev-parse", "HEAD"], cwd=dir_path
     ).strip()

scripts/completion/dvc.bash

@@ -34,9 +34,10 @@ _dvc_install=''
 _dvc_lock='$(compgen -G *.dvc)'
 _dvc_metrics='add modify rmeove show'
 _dvc_metrics_add='-t --type -x --xpath $(compgen -G *)'
+_dvc_metrics_show='$(-t --type -x --xpath -a --all-branches -T --all-tags -R --recursive $(compgen -G *)'
+_dvc_metrics_diff='--targets -t --type -x --xpath -R --show-json'
 _dvc_metrics_modify='-t --type -x --xpath $(compgen -G *)'
 _dvc_metrics_remove='$(compgen -G *)'
-_dvc_metrics_show='$(-t --type -x --xpath -a --all-branches -T --all-tags -R --recursive $(compgen -G *)'
 _dvc_move='$(compgen -G *)'
 _dvc_pipeline='list show'
 _dvc_pipeline_list=''

scripts/completion/dvc.zsh

@@ -22,7 +22,7 @@ _dvc_commands() {
     "fetch:Fetch data files from a DVC remote storage."
     "get-url:Download or copy files from URL."
     "get:Download data from DVC repository."
-    "gc:Collect unused data from DVC cache or a remote storage."
+    "gc:Garbage collect unused objects from cache or remote storage."
     "import-url:Download or copy file from URL and take it under DVC control."
     "import:Download data from DVC repository and take it under DVC control."
     "init:Initialize DVC in the current directory."
@@ -99,7 +99,8 @@ _dvc_destroy=(
 _dvc_diff=(
   "--show-json[Format the output into a JSON]"
   "--checksums[Display checksums for each entry]"
-  {1,2}":Git revision (e.g. branch, tag, SHA):"
+  "1:Git reference to the older version:"
+  "2:Git reference to the newer version:"
 )
 
 _dvc_fetch=(
@@ -119,7 +120,7 @@ _dvc_geturl=(
 
 _dvc_get=(
   {-o,--out}"[Destination path to put data to.]:OUT:_files -/"
-  "--rev[Git revision (e.g. branch, tag, SHA)]:Revision:"
+  "--rev[Git revision (e.g. SHA, branch, tag)]:Revision:"
   "--show-url[Returns path/url to the location in remote for given path]"
   "1:URL:"
   "2:Path:"
@@ -143,7 +144,7 @@ _dvc_importurl=(
 
 _dvc_import=(
   {-o,--out}"[Destination path to put data to.]:OUT:_files -/"
-  "--rev[DVC repository git revision.]:Commit hash:"
+  "--rev[Git revision (e.g. SHA, branch, tag)]:Commit hash:"
   "1:URL:"
   "2:Path:"
 )
@@ -160,7 +161,7 @@ _dvc_lock=(
 )
 
 _dvc_metrics=(
-  "1:Sub command:(show add modify remove)"
+  "1:Sub command:(add show diff modify remove)"
 )
 
 _dvc_move=(

setup.py

@@ -133,7 +133,7 @@ setup(
     description="Git for data scientists - manage your code and data together",
     long_description=open("README.rst", "r").read(),
     author="Dmitry Petrov",
-    author_email="dmitry@dataversioncontrol.com",
+    author_email="dmitry@dvc.org",
     download_url="https://github.com/iterative/dvc",
     license="Apache License 2.0",
     install_requires=install_requires,

tests/func/test_data_cloud.py

@@ -498,9 +498,9 @@ class TestWarnOnOutdatedStage(TestDvc):
             self._caplog.clear()
             self.main(["status", "-c"])
             expected_warning = (
-                "Output 'bar'(Stage: 'bar.dvc') is missing version info."
-                " Cache for it will not be collected."
-                " Use dvc repro to get your pipeline up to date."
+                "Output 'bar'(Stage: 'bar.dvc') is missing version info. "
+                "Cache for it will not be collected. "
+                "Use `dvc repro` to get your pipeline up to date."
             )
 
             assert expected_warning in self._caplog.text