Merge pull request #2112 from jorgeorpinel/master

dvc: "DVC-file" term revision, `targets` argument help update, other small changes

dvc/command/add.py

@@ -57,6 +57,6 @@ def add_parser(subparsers, parent_parser):
         "-f", "--file", help="Specify name of the DVC-file it generates."
     )
     add_parser.add_argument(
-        "targets", nargs="+", help="Input files/directories."
+        "targets", nargs="+", help="Input files/directories to add."
     )
     add_parser.set_defaults(func=CmdAdd)

dvc/command/checkout.py

@@ -51,5 +51,10 @@ def add_parser(subparsers, parent_parser):
         default=False,
         help="Checkout all subdirectories of the specified directory.",
     )
-    checkout_parser.add_argument("targets", nargs="*", help="DVC-files.")
+    checkout_parser.add_argument(
+        "targets",
+        nargs="*",
+        help="DVC-files to checkout. Optional. "
+        "(Finds all DVC-files in the workspace by default.)",
+    )
     checkout_parser.set_defaults(func=CmdCheckout)

dvc/command/commit.py

@@ -65,6 +65,9 @@ def add_parser(subparsers, parent_parser):
         help="Commit cache for subdirectories of the specified directory.",
     )
     commit_parser.add_argument(
-        "targets", nargs="*", default=None, help="DVC-files."
+        "targets",
+        nargs="*",
+        help="DVC-files to commit. Optional. "
+        "(Finds all DVC-files in the workspace by default.)",
     )
     commit_parser.set_defaults(func=CmdCommit)

dvc/command/data_sync.py

@@ -116,11 +116,8 @@ def shared_parent_parser():
     shared_parent_parser.add_argument(
         "targets",
         nargs="*",
-        default=None,
-        help=(
-            "Limit the scope to these DVC-files."
-            " With -R a directory to search DVC-files in can be specified."
-        ),
+        help="Limit command scope to these DVC-files. "
+        "Using -R, directories to search DVC-files in can also be given.",
     )
 
     return shared_parent_parser

dvc/command/diff.py

@@ -157,7 +157,7 @@ def add_parser(subparsers, parent_parser):
     diff_parser.add_argument(
         "b_ref",
         help=(
-            "Git reference untill which diff calculates, if omitted "
+            "Git reference until which diff calculates, if omitted "
             "diff shows the difference between current HEAD and a_ref"
         ),
         nargs="?",

dvc/command/lock.py

@@ -37,7 +37,7 @@ class CmdUnlock(CmdLockBase):
 
 
 def add_parser(subparsers, parent_parser):
-    LOCK_HELP = "Lock DVC-file."
+    LOCK_HELP = "Lock DVC-files."
     lock_parser = subparsers.add_parser(
         "lock",
         parents=[parent_parser],
@@ -45,10 +45,10 @@ def add_parser(subparsers, parent_parser):
         help=LOCK_HELP,
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
-    lock_parser.add_argument("targets", nargs="+", help="DVC-files.")
+    lock_parser.add_argument("targets", nargs="+", help="DVC-files to lock.")
     lock_parser.set_defaults(func=CmdLock)
 
-    UNLOCK_HELP = "Unlock DVC-file."
+    UNLOCK_HELP = "Unlock DVC-files."
     unlock_parser = subparsers.add_parser(
         "unlock",
         parents=[parent_parser],
@@ -56,5 +56,7 @@ def add_parser(subparsers, parent_parser):
         help=UNLOCK_HELP,
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
-    unlock_parser.add_argument("targets", nargs="+", help="DVC-files.")
+    unlock_parser.add_argument(
+        "targets", nargs="+", help="DVC-files to unlock."
+    )
     unlock_parser.set_defaults(func=CmdUnlock)

dvc/command/pipeline.py

@@ -197,7 +197,7 @@ def add_parser(subparsers, parent_parser):
 
     fix_subparsers(pipeline_subparsers)
 
-    PIPELINE_SHOW_HELP = "Show pipeline."
+    PIPELINE_SHOW_HELP = "Show pipelines."
     pipeline_show_parser = pipeline_subparsers.add_parser(
         "show",
         parents=[parent_parser],
@@ -246,7 +246,10 @@ def add_parser(subparsers, parent_parser):
         help="Output DAG as Dependencies Tree.",
     )
     pipeline_show_parser.add_argument(
-        "targets", nargs="*", help="DVC-files. 'Dvcfile' by default."
+        "targets",
+        nargs="*",
+        help="DVC-files to show pipeline for. Optional. "
+        "(Finds all DVC-files in the workspace by default.)",
     )
     pipeline_show_parser.set_defaults(func=CmdPipelineShow)
 

dvc/command/remote.py

@@ -89,7 +89,7 @@ def add_parser(subparsers, parent_parser):
         help=REMOTE_ADD_HELP,
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
-    remote_add_parser.add_argument("name", help="Name.")
+    remote_add_parser.add_argument("name", help="Name of the remote")
     remote_add_parser.add_argument(
         "url",
         help="URL. See full list of supported urls at " "man.dvc.org/remote",
@@ -138,7 +138,9 @@ def add_parser(subparsers, parent_parser):
         help=REMOTE_REMOVE_HELP,
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
-    remote_remove_parser.add_argument("name", help="Name")
+    remote_remove_parser.add_argument(
+        "name", help="Name of the remote to remove."
+    )
     remote_remove_parser.set_defaults(func=CmdRemoteRemove)
 
     REMOTE_MODIFY_HELP = "Modify remote."
@@ -149,9 +151,13 @@ def add_parser(subparsers, parent_parser):
         help=REMOTE_MODIFY_HELP,
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
-    remote_modify_parser.add_argument("name", help="Name.")
-    remote_modify_parser.add_argument("option", help="Option.")
-    remote_modify_parser.add_argument("value", nargs="?", help="Value.")
+    remote_modify_parser.add_argument("name", help="Name of the remote.")
+    remote_modify_parser.add_argument(
+        "option", help="Name of the option to modify."
+    )
+    remote_modify_parser.add_argument(
+        "value", nargs="?", help="(optional) Value of the option."
+    )
     remote_modify_parser.add_argument(
         "-u",
         "--unset",

dvc/command/remove.py

@@ -43,7 +43,7 @@ class CmdRemove(CmdBase):
 
 
 def add_parser(subparsers, parent_parser):
-    REMOVE_HELP = "Remove outputs of DVC-file."
+    REMOVE_HELP = "Remove DVC-file outputs."
     remove_parser = subparsers.add_parser(
         "remove",
         parents=[parent_parser],
@@ -73,5 +73,10 @@ def add_parser(subparsers, parent_parser):
         default=False,
         help="Force purge.",
     )
-    remove_parser.add_argument("targets", nargs="+", help="DVC-files.")
+    remove_parser.add_argument(
+        "targets",
+        nargs="+",
+        help="DVC-files to remove. Optional. "
+        "(Finds all DVC-files in the workspace by default.)",
+    )
     remove_parser.set_defaults(func=CmdRemove)

dvc/command/repro.py

@@ -58,7 +58,7 @@ class CmdRepro(CmdBase):
 
 
 def add_parser(subparsers, parent_parser):
-    REPRO_HELP = "Check for changes and reproduce DVC-file and dependencies."
+    REPRO_HELP = "Check for changes and reproduce stages and dependencies."
     repro_parser = subparsers.add_parser(
         "repro",
         parents=[parent_parser],
@@ -69,7 +69,7 @@ def add_parser(subparsers, parent_parser):
     repro_parser.add_argument(
         "targets",
         nargs="*",
-        help="DVC-file to reproduce (default - 'Dvcfile').",
+        help="DVC-file to reproduce. 'Dvcfile' by default.",
     )
     repro_parser.add_argument(
         "-f",

dvc/command/unprotect.py

@@ -23,7 +23,7 @@ class CmdUnprotect(CmdBase):
 
 
 def add_parser(subparsers, parent_parser):
-    UNPROTECT_HELP = "Unprotect a data file/directory."
+    UNPROTECT_HELP = "Unprotect data files or directories."
     unprotect_parser = subparsers.add_parser(
         "unprotect",
         parents=[parent_parser],
@@ -32,6 +32,6 @@ def add_parser(subparsers, parent_parser):
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     unprotect_parser.add_argument(
-        "targets", nargs="+", help="Data files/directory."
+        "targets", nargs="+", help="Data files/directories to unprotect."
     )
     unprotect_parser.set_defaults(func=CmdUnprotect)

dvc/exceptions.py

@@ -62,7 +62,7 @@ class OutputNotFoundError(DvcException):
 
     def __init__(self, output):
         super(OutputNotFoundError, self).__init__(
-            "unable to find stage file with output '{path}'".format(
+            "unable to find DVC-file with output '{path}'".format(
                 path=relpath(output)
             )
         )
@@ -74,7 +74,7 @@ class StagePathAsOutputError(DvcException):
 
     Args:
         cwd (str): path to the directory.
-        fname (str): path to the stage file that has cwd specified as an
+        fname (str): path to the DVC-file that has cwd specified as an
             output.
     """
 
@@ -216,7 +216,7 @@ class StageFileCorruptedError(DvcException):
     def __init__(self, path, cause=None):
         path = relpath(path)
         super(StageFileCorruptedError, self).__init__(
-            "unable to read stage file: {} "
+            "unable to read DVC-file: {} "
             "YAML file structure is corrupted".format(path),
             cause=cause,
         )

dvc/repo/add.py

@@ -22,7 +22,7 @@ def add(repo, target, recursive=False, no_commit=False, fname=None):
         logger.warning(
             "You are adding a large directory '{target}' recursively,"
             " consider tracking it as a whole instead.\n"
-            "{purple}HINT:{nc} Remove the generated stage files and then"
+            "{purple}HINT:{nc} Remove the generated DVC-file and then"
             " run {cyan}dvc add {target}{nc}".format(
                 purple=colorama.Fore.MAGENTA,
                 cyan=colorama.Fore.CYAN,

dvc/repo/metrics/show.py

@@ -177,7 +177,7 @@ def _collect_metrics(repo, path, recursive, typ, xpath, branch):
             outs = repo.find_outs_by_path(path, outs=outs, recursive=recursive)
         except OutputNotFoundError:
             logger.debug(
-                "stage file not for found for '{}' in branch '{}'".format(
+                "DVC-file not for found for '{}' in branch '{}'".format(
                     path, branch
                 )
             )

dvc/repo/move.py

@@ -17,7 +17,7 @@ def move(self, from_path, to_path):
     to reflect the change on the pipeline.
 
     If the output has the same name as its stage, it would
-    also rename the corresponding stage file.
+    also rename the corresponding DVC-file.
 
     E.g.
           Having: (hello, hello.dvc)

dvc/stage.py

@@ -35,7 +35,7 @@ class StageCmdFailedError(DvcException):
 
 class StageFileFormatError(DvcException):
     def __init__(self, fname, e):
-        msg = "stage file '{}' format error: {}".format(fname, str(e))
+        msg = "DVC-file '{}' format error: {}".format(fname, str(e))
         super(StageFileFormatError, self).__init__(msg)
 
 
@@ -183,7 +183,7 @@ class Stage(object):
 
     @property
     def is_data_source(self):
-        """Whether the stage file was created with `dvc add` or `dvc import`"""
+        """Whether the DVC-file was created with `dvc add` or `dvc import`"""
         return self.cmd is None
 
     @staticmethod
@@ -213,7 +213,7 @@ class Stage(object):
 
     @property
     def is_import(self):
-        """Whether the stage file was created with `dvc import`."""
+        """Whether the DVC-file was created with `dvc import`."""
         return not self.cmd and len(self.deps) == 1 and len(self.outs) == 1
 
     @property
@@ -453,9 +453,9 @@ class Stage(object):
         if wdir is None and cwd is not None:
             if fname is not None and os.path.basename(fname) != fname:
                 raise StageFileBadNameError(
-                    "stage file name '{fname}' may not contain subdirectories"
+                    "DVC-file name '{fname}' may not contain subdirectories"
                     " if '-c|--cwd' (deprecated) is specified. Use '-w|--wdir'"
-                    " along with '-f' to specify stage file path and working"
+                    " along with '-f' to specify DVC-file path with working"
                     " directory.".format(fname=fname)
                 )
             wdir = cwd
@@ -559,7 +559,7 @@ class Stage(object):
     def _check_dvc_filename(fname):
         if not Stage.is_valid_filename(fname):
             raise StageFileBadNameError(
-                "bad stage filename '{}'. Stage files should be named"
+                "bad DVC-file name '{}'. DVC-files should be named"
                 " 'Dvcfile' or have a '.dvc' suffix (e.g. '{}.dvc').".format(
                     relpath(fname), os.path.basename(fname)
                 )
@@ -663,10 +663,10 @@ class Stage(object):
         if self.PARAM_MD5 in d.keys():
             del d[self.PARAM_MD5]
 
-        # Ignore the wdir default value. In this case stage file w/o
+        # Ignore the wdir default value. In this case DVC-file w/o
         # wdir has the same md5 as a file with the default value specified.
         # It's important for backward compatibility with pipelines that
-        # didn't have WDIR in their stage files.
+        # didn't have WDIR in their DVC-files.
         if d.get(self.PARAM_WDIR) == ".":
             del d[self.PARAM_WDIR]
 

scripts/completion/dvc.zsh

@@ -144,7 +144,7 @@ _dvc_move=(
 )
 
 _dvc_pipeline=(
-  "1:Sub command:(show,list)"
+  "1:Sub command:(show list)"
 )
 
 _dvc_pull=(

tests/func/test_add.py

@@ -96,7 +96,7 @@ class TestAddCmdDirectoryRecursive(TestDvc):
         warning = (
             "You are adding a large directory 'large-dir' recursively,"
             " consider tracking it as a whole instead.\n"
-            "{purple}HINT:{nc} Remove the generated stage files and then"
+            "{purple}HINT:{nc} Remove the generated DVC-file and then"
             " run {cyan}dvc add large-dir{nc}".format(
                 purple=colorama.Fore.MAGENTA,
                 cyan=colorama.Fore.CYAN,
@@ -434,7 +434,7 @@ class TestShouldThrowProperExceptionOnCorruptedStageFile(TestDvc):
         assert 1 == ret
 
         expected_error = (
-            "unable to read stage file: {} "
+            "unable to read DVC-file: {} "
             "YAML file structure is corrupted".format(foo_stage)
         )
 
@@ -475,6 +475,7 @@ class TestShouldCleanUpAfterFailedAdd(TestDvcGit):
         self.assertEqual(0, ret)
 
         foo_stage_file = self.FOO + Stage.STAGE_FILE_SUFFIX
+
         # corrupt stage file
         with open(foo_stage_file, "a+") as file:
             file.write("this will break yaml file structure")

tests/func/test_repro.py

@@ -1558,7 +1558,7 @@ def test_dvc_formatting_retained(dvc_repo, foo_copy):
     root = pathlib.Path(dvc_repo.root_dir)
     stage_file = root / foo_copy["stage_fname"]
 
-    # Add comments and custom formatting to stage file
+    # Add comments and custom formatting to DVC-file
     lines = list(map(_format_dvc_line, stage_file.read_text().splitlines()))
     lines.insert(0, "# Starting comment")
     stage_text = "".join(l + "\n" for l in lines)

tests/func/test_stage.py

@@ -172,7 +172,7 @@ def test_md5_ignores_comments(repo_dir, dvc_repo):
 def test_meta_is_preserved(dvc_repo):
     stage, = dvc_repo.add("foo")
 
-    # Add meta to stage file
+    # Add meta to DVC-file
     data = load_stage_file(stage.path)
     data["meta"] = {"custom_key": 42}
     dump_stage_file(stage.path, data)