list: rename target param to path, update docs (iterative#3462)

Close iterative#3381

dvc/command/ls/__init__.py

@@ -30,7 +30,7 @@ def run(self):
         try:
             entries = Repo.ls(
                 self.args.url,
-                self.args.target,
+                self.args.path,
                 rev=self.args.rev,
                 recursive=self.args.recursive,
                 outs_only=self.args.outs_only,
@@ -45,24 +45,18 @@ def run(self):
 
 
 def add_parser(subparsers, parent_parser):
-    LIST_HELP = "List files and DVC outputs in the repo."
+    LIST_HELP = (
+        "List repository contents, including files"
+        " and directories tracked by DVC and by Git."
+    )
     list_parser = subparsers.add_parser(
         "list",
         parents=[parent_parser],
         description=append_doc_link(LIST_HELP, "list"),
         help=LIST_HELP,
         formatter_class=argparse.RawTextHelpFormatter,
     )
-    list_parser.add_argument(
-        "url",
-        help="Supported urls:\n"
-        "/path/to/file\n"
-        "/path/to/directory\n"
-        "C:\\\\path\\to\\file\n"
-        "C:\\\\path\\to\\directory\n"
-        "https://github.com/path/to/repo\n"
-        "[email protected]:path/to/repo.git\n",
-    )
+    list_parser.add_argument("url", help="Location of DVC repository to list")
     list_parser.add_argument(
         "-R",
         "--recursive",
@@ -76,7 +70,7 @@ def add_parser(subparsers, parent_parser):
         "--rev", nargs="?", help="Git revision (e.g. branch, tag, SHA)"
     )
     list_parser.add_argument(
-        "target",
+        "path",
         nargs="?",
         help="Path to directory within the repository to list outputs for",
     )

dvc/exceptions.py

@@ -295,11 +295,11 @@ def __init__(self, code, reason):
 class PathMissingError(DvcException):
     default_msg = (
         "The path '{}' does not exist in the target repository '{}'"
-        " neither as an output nor a git-handled file."
+        " neither as a DVC output nor as a Git-tracked file."
     )
     default_msg_output_only = (
         "The path '{}' does not exist in the target repository '{}'"
-        " as an output."
+        " as an DVC output."
     )
 
     def __init__(self, path, repo, output_only=False):

dvc/repo/ls.py

@@ -6,13 +6,13 @@
 
 @staticmethod
 def ls(
-    url, target=None, rev=None, recursive=None, outs_only=False,
+    url, path=None, rev=None, recursive=None, outs_only=False,
 ):
     """Methods for getting files and outputs for the repo.
 
     Args:
         url (str): the repo url
-        target (str, optional): relative path into the repo
+        path (str, optional): relative path into the repo
         rev (str, optional): SHA commit, branch or tag name
         recursive (bool, optional): recursively walk the repo
         outs_only (bool, optional): show only DVC-artifacts
@@ -34,25 +34,25 @@ def ls(
     from dvc.utils import relpath
 
     with external_repo(url, rev) as repo:
-        target_path_info = _get_target_path_info(repo, target)
+        path_info = _get_path_info(repo, path)
         fs_nodes = []
         if isinstance(repo, Repo):
-            fs_nodes.extend(_ls_outs_repo(repo, target_path_info, recursive))
+            fs_nodes.extend(_ls_outs_repo(repo, path_info, recursive))
 
         if not outs_only:
-            fs_nodes.extend(_ls_files_repo(target_path_info, recursive))
+            fs_nodes.extend(_ls_files_repo(path_info, recursive))
 
-        if target and not fs_nodes:
-            raise PathMissingError(target, repo, output_only=outs_only)
+        if path and not fs_nodes:
+            raise PathMissingError(path, repo, output_only=outs_only)
 
         fs_nodes = {n["path_info"]: n for n in fs_nodes}.values()
 
         def get_entry(fs_node):
-            path_info = fs_node["path_info"]
+            node_path_info = fs_node["path_info"]
             path = (
-                path_info.name
-                if path_info == target_path_info
-                else relpath(path_info, target_path_info)
+                node_path_info.name
+                if node_path_info == path_info
+                else relpath(node_path_info, path_info)
             )
             return {
                 "path": path,
@@ -123,12 +123,12 @@ def get_first_segment(out):
     ]
 
 
-def _get_target_path_info(repo, target=None):
+def _get_path_info(repo, path=None):
     from dvc.path_info import PathInfo
 
-    if not target:
+    if not path:
         return PathInfo(repo.root_dir)
-    return PathInfo(repo.root_dir, target)
+    return PathInfo(repo.root_dir, path)
 
 
 def _get_fs_node(path_info, out=None):

scripts/completion/dvc.zsh

@@ -27,7 +27,7 @@ _dvc_commands() {
     "import:Download data from DVC repository and take it under DVC control."
     "init:Initialize DVC in the current directory."
     "install:Install DVC git hooks into the repository."
-    "list:List files."
+    "list:List repository contents, including files and directories tracked by DVC and by Git."
     "lock:Lock DVC-file."
     "metrics:Commands to add, manage, collect and display metrics."
     "move:Rename or move a DVC controlled data file or a directory."
@@ -168,7 +168,7 @@ _dvc_list=(
   {-R,--recursive}"[Recursively add each file under the directory.]"
   "--outs-only[Only outputs DVC-outs.]"
   "1:URL:"
-  "2:Target:"
+  "2:Path:"
 )
 
 _dvc_metrics=(

tests/func/test_ls.py

@@ -138,11 +138,11 @@ def test_ls_repo_outs_only_recursive(tmp_dir, dvc, scm):
     )
 
 
-def test_ls_repo_with_target_dir(tmp_dir, dvc, scm):
+def test_ls_repo_with_path_dir(tmp_dir, dvc, scm):
     tmp_dir.scm_gen(FS_STRUCTURE, commit="init")
     tmp_dir.dvc_gen(DVC_STRUCTURE, commit="dvc")
 
-    files = Repo.ls(fspath(tmp_dir), target="model")
+    files = Repo.ls(fspath(tmp_dir), path="model")
     match_files(
         files,
         (
@@ -155,21 +155,21 @@ def test_ls_repo_with_target_dir(tmp_dir, dvc, scm):
     )
 
 
-def test_ls_repo_with_target_dir_outs_only_empty(tmp_dir, dvc, scm):
+def test_ls_repo_with_path_dir_outs_only_empty(tmp_dir, dvc, scm):
     tmp_dir.scm_gen(FS_STRUCTURE, commit="init")
     tmp_dir.dvc_gen(DVC_STRUCTURE, commit="dvc")
     tmp_dir.scm_gen({"folder/.keep": "content"}, commit="add .keep")
 
     with pytest.raises(PathMissingError):
-        Repo.ls(fspath(tmp_dir), target="folder", outs_only=True)
+        Repo.ls(fspath(tmp_dir), path="folder", outs_only=True)
 
 
-def test_ls_repo_with_target_subdir(tmp_dir, dvc, scm):
+def test_ls_repo_with_path_subdir(tmp_dir, dvc, scm):
     tmp_dir.scm_gen(FS_STRUCTURE, commit="init")
     tmp_dir.dvc_gen(DVC_STRUCTURE, commit="dvc")
 
-    target = os.path.join("data", "subcontent")
-    files = Repo.ls(fspath(tmp_dir), target)
+    path = os.path.join("data", "subcontent")
+    files = Repo.ls(fspath(tmp_dir), path)
     match_files(
         files,
         (
@@ -181,61 +181,61 @@ def test_ls_repo_with_target_subdir(tmp_dir, dvc, scm):
     )
 
 
-def test_ls_repo_with_target_subdir_outs_only(tmp_dir, dvc, scm):
+def test_ls_repo_with_path_subdir_outs_only(tmp_dir, dvc, scm):
     tmp_dir.scm_gen(FS_STRUCTURE, commit="init")
     tmp_dir.dvc_gen(DVC_STRUCTURE, commit="dvc")
 
-    target = os.path.join("data", "subcontent")
-    files = Repo.ls(fspath(tmp_dir), target, outs_only=True)
+    path = os.path.join("data", "subcontent")
+    files = Repo.ls(fspath(tmp_dir), path, outs_only=True)
     match_files(files, ((("data.xml",), True), (("statistics",), False),))
 
 
-def test_ls_repo_with_target_subdir_outs_only_recursive(tmp_dir, dvc, scm):
+def test_ls_repo_with_path_subdir_outs_only_recursive(tmp_dir, dvc, scm):
     tmp_dir.scm_gen(FS_STRUCTURE, commit="init")
     tmp_dir.dvc_gen(DVC_STRUCTURE, commit="dvc")
 
-    target = os.path.join("data", "subcontent")
-    files = Repo.ls(fspath(tmp_dir), target, outs_only=True, recursive=True)
+    path = os.path.join("data", "subcontent")
+    files = Repo.ls(fspath(tmp_dir), path, outs_only=True, recursive=True)
     match_files(
         files, ((("data.xml",), True), (("statistics", "data.csv"), True),)
     )
 
 
-def test_ls_repo_with_target_file_out(tmp_dir, dvc, scm):
+def test_ls_repo_with_path_file_out(tmp_dir, dvc, scm):
     tmp_dir.scm_gen(FS_STRUCTURE, commit="init")
     tmp_dir.dvc_gen(DVC_STRUCTURE, commit="dvc")
 
-    target = os.path.join("data", "subcontent", "data.xml")
-    files = Repo.ls(fspath(tmp_dir), target)
+    path = os.path.join("data", "subcontent", "data.xml")
+    files = Repo.ls(fspath(tmp_dir), path)
     match_files(files, ((("data.xml",), True),))
 
 
-def test_ls_repo_with_file_target_fs(tmp_dir, dvc, scm):
+def test_ls_repo_with_file_path_fs(tmp_dir, dvc, scm):
     tmp_dir.scm_gen(FS_STRUCTURE, commit="init")
     tmp_dir.dvc_gen(DVC_STRUCTURE, commit="dvc")
 
-    target = "README.md"
-    files = Repo.ls(fspath(tmp_dir), target, recursive=True)
+    path = "README.md"
+    files = Repo.ls(fspath(tmp_dir), path, recursive=True)
     match_files(files, ((("README.md",), False),))
 
 
-def test_ls_repo_with_missed_target(tmp_dir, dvc, scm):
+def test_ls_repo_with_missed_path(tmp_dir, dvc, scm):
     tmp_dir.scm_gen(FS_STRUCTURE, commit="init")
     tmp_dir.dvc_gen(DVC_STRUCTURE, commit="dvc")
 
     with pytest.raises(PathMissingError) as exc_info:
-        Repo.ls(fspath(tmp_dir), target="missed_target")
+        Repo.ls(fspath(tmp_dir), path="missed_path")
     assert not exc_info.value.output_only
 
 
-def test_ls_repo_with_missed_target_outs_only(tmp_dir, dvc, scm):
+def test_ls_repo_with_missed_path_outs_only(tmp_dir, dvc, scm):
     tmp_dir.scm_gen(FS_STRUCTURE, commit="init")
     tmp_dir.dvc_gen(DVC_STRUCTURE, commit="dvc")
 
     with pytest.raises(PathMissingError) as exc_info:
         Repo.ls(
             fspath(tmp_dir),
-            target="missed_target",
+            path="missed_path",
             recursive=True,
             outs_only=True,
         )
@@ -276,19 +276,19 @@ def test_ls_repo_with_removed_dvc_dir_recursive(tmp_dir, dvc, scm):
     )
 
 
-def test_ls_repo_with_removed_dvc_dir_with_target_dir(tmp_dir, dvc, scm):
+def test_ls_repo_with_removed_dvc_dir_with_path_dir(tmp_dir, dvc, scm):
     create_dvc_pipeline(tmp_dir, dvc)
 
-    target = "out"
-    files = Repo.ls(fspath(tmp_dir), target)
+    path = "out"
+    files = Repo.ls(fspath(tmp_dir), path)
     match_files(files, ((("file",), True),))
 
 
-def test_ls_repo_with_removed_dvc_dir_with_target_file(tmp_dir, dvc, scm):
+def test_ls_repo_with_removed_dvc_dir_with_path_file(tmp_dir, dvc, scm):
     create_dvc_pipeline(tmp_dir, dvc)
 
-    target = os.path.join("out", "file")
-    files = Repo.ls(fspath(tmp_dir), target)
+    path = os.path.join("out", "file")
+    files = Repo.ls(fspath(tmp_dir), path)
     match_files(files, ((("file",), True),))
 
 
@@ -358,14 +358,14 @@ def test_ls_remote_git_only_repo_recursive(git_dir):
     )
 
 
-def test_ls_remote_repo_with_target_dir(erepo_dir):
+def test_ls_remote_repo_with_path_dir(erepo_dir):
     with erepo_dir.chdir():
         erepo_dir.scm_gen(FS_STRUCTURE, commit="init")
         erepo_dir.dvc_gen(DVC_STRUCTURE, commit="dvc")
 
     url = "file://{}".format(erepo_dir)
-    target = "model"
-    files = Repo.ls(url, target)
+    path = "model"
+    files = Repo.ls(url, path)
     match_files(
         files,
         (