dvc: cmd arg names (metavars) to match docs

jorgeorpinel · jorgeorpinel · commit 2632344636a2 · 2020-04-16T22:01:25.000-05:00
for #3626
diff --git a/dvc/command/data_sync.py b/dvc/command/data_sync.py
@@ -89,7 +89,11 @@ def shared_parent_parser():
         add_help=False, parents=[get_parent_parser()]
     )
     shared_parent_parser.add_argument(
-        "-j", "--jobs", type=int, help="Number of jobs to run simultaneously."
+        "-j",
+        "--jobs",
+        type=int,
+        help="Number of jobs to run simultaneously.",
+        metavar="<number>",
     )
     shared_parent_parser.add_argument(
         "targets",
@@ -115,7 +119,7 @@ def add_parser(subparsers, _parent_parser):
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     pull_parser.add_argument(
-        "-r", "--remote", help="Remote repository to pull from."
+        "-r", "--remote", help="Remote storage to pull from", metavar="<name>",
     )
     pull_parser.add_argument(
         "-a",
@@ -171,7 +175,7 @@ def add_parser(subparsers, _parent_parser):
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     push_parser.add_argument(
-        "-r", "--remote", help="Remote repository to push to."
+        "-r", "--remote", help="Remote storage to push to", metavar="<name>",
     )
     push_parser.add_argument(
         "-a",
@@ -223,7 +227,10 @@ def add_parser(subparsers, _parent_parser):
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     fetch_parser.add_argument(
-        "-r", "--remote", help="Remote repository to fetch from."
+        "-r",
+        "--remote",
+        help="Remote storage to fetch from",
+        metavar="<name>",
     )
     fetch_parser.add_argument(
         "-a",
@@ -292,7 +299,10 @@ def add_parser(subparsers, _parent_parser):
         help="Show status of a local cache compared to a remote repository.",
     )
     status_parser.add_argument(
-        "-r", "--remote", help="Remote repository to compare local cache to."
+        "-r",
+        "--remote",
+        help="Remote storage to compare local cache to",
+        metavar="<name>",
     )
     status_parser.add_argument(
         "-a",
diff --git a/dvc/command/gc.py b/dvc/command/gc.py
@@ -109,7 +109,10 @@ def add_parser(subparsers, parent_parser):
         help="Collect garbage in remote repository.",
     )
     gc_parser.add_argument(
-        "-r", "--remote", help="Remote storage to collect garbage in."
+        "-r",
+        "--remote",
+        help="Remote storage to collect garbage in",
+        metavar="<name>",
     )
     gc_parser.add_argument(
         "-f",
@@ -119,7 +122,11 @@ def add_parser(subparsers, parent_parser):
         help="Force garbage collection - automatically agree to all prompts.",
     )
     gc_parser.add_argument(
-        "-j", "--jobs", type=int, help="Number of jobs to run simultaneously."
+        "-j",
+        "--jobs",
+        type=int,
+        help="Number of jobs to run simultaneously.",
+        metavar="<number>",
     )
     gc_parser.add_argument(
         "-p",
@@ -130,5 +137,6 @@ def add_parser(subparsers, parent_parser):
         help="Keep data files required by these projects "
         "in addition to the current one. "
         "Useful if you share a single cache across repos.",
+        metavar="<paths>",
     )
     gc_parser.set_defaults(func=CmdGC)
diff --git a/dvc/command/get.py b/dvc/command/get.py
@@ -66,10 +66,17 @@ def add_parser(subparsers, parent_parser):
         "path", help="Path to a file or directory within the repository"
     )
     get_parser.add_argument(
-        "-o", "--out", nargs="?", help="Destination path to download files to"
+        "-o",
+        "--out",
+        nargs="?",
+        help="Destination path to download files to",
+        metavar="<path>",
     )
     get_parser.add_argument(
-        "--rev", nargs="?", help="Git revision (e.g. SHA, branch, tag)"
+        "--rev",
+        nargs="?",
+        help="Git revision (e.g. SHA, branch, tag)",
+        metavar="<commit>",
     )
     get_parser.add_argument(
         "--show-url",
diff --git a/dvc/command/imp.py b/dvc/command/imp.py
@@ -48,9 +48,16 @@ def add_parser(subparsers, parent_parser):
         "path", help="Path to a file or directory within the repository"
     )
     import_parser.add_argument(
-        "-o", "--out", nargs="?", help="Destination path to download files to"
+        "-o",
+        "--out",
+        nargs="?",
+        help="Destination path to download files to",
+        metavar="<path>",
     )
     import_parser.add_argument(
-        "--rev", nargs="?", help="Git revision (e.g. SHA, branch, tag)"
+        "--rev",
+        nargs="?",
+        help="Git revision (e.g. SHA, branch, tag)",
+        metavar="<commit>",
     )
     import_parser.set_defaults(func=CmdImport)
diff --git a/dvc/command/imp_url.py b/dvc/command/imp_url.py
@@ -59,6 +59,9 @@ def add_parser(subparsers, parent_parser):
         "out", nargs="?", help="Destination path to put files to."
     )
     import_parser.add_argument(
-        "-f", "--file", help="Specify name of the DVC-file it generates."
+        "-f",
+        "--file",
+        help="Specify name of the DVC-file this command will generate.",
+        metavar="<filename>",
     )
     import_parser.set_defaults(func=CmdImportUrl)
diff --git a/dvc/command/ls/__init__.py b/dvc/command/ls/__init__.py
@@ -67,7 +67,10 @@ def add_parser(subparsers, parent_parser):
         "--outs-only", action="store_true", help="Show only DVC outputs."
     )
     list_parser.add_argument(
-        "--rev", nargs="?", help="Git revision (e.g. branch, tag, SHA)"
+        "--rev",
+        nargs="?",
+        help="Git revision (e.g. SHA, branch, tag)",
+        metavar="<commit>",
     )
     list_parser.add_argument(
         "path",
diff --git a/dvc/command/metrics.py b/dvc/command/metrics.py
@@ -198,9 +198,10 @@ def add_parser(subparsers, parent_parser):
             "It can be detected by the file extension automatically. "
             "Unsupported types will be treated as raw."
         ),
+        metavar="<type>",
     )
     metrics_show_parser.add_argument(
-        "-x", "--xpath", help="json/tsv/htsv/csv/hcsv path."
+        "-x", "--xpath", help="json/tsv/htsv/csv/hcsv path.", metavar="<path>",
     )
     metrics_show_parser.add_argument(
         "-a",
@@ -243,10 +244,13 @@ def add_parser(subparsers, parent_parser):
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     metrics_add_parser.add_argument(
-        "-t", "--type", help="Type of metrics (raw/json/tsv/htsv/csv/hcsv)."
+        "-t",
+        "--type",
+        help="Type of metrics (raw/json/tsv/htsv/csv/hcsv).",
+        metavar="<type>",
     )
     metrics_add_parser.add_argument(
-        "-x", "--xpath", help="json/tsv/htsv/csv/hcsv path."
+        "-x", "--xpath", help="json/tsv/htsv/csv/hcsv path.", metavar="<path>",
     )
     metrics_add_parser.add_argument("path", help="Path to a metric file.")
     metrics_add_parser.set_defaults(func=CmdMetricsAdd)
@@ -260,10 +264,13 @@ def add_parser(subparsers, parent_parser):
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     metrics_modify_parser.add_argument(
-        "-t", "--type", help="Type of metrics (raw/json/tsv/htsv/csv/hcsv)."
+        "-t",
+        "--type",
+        help="Type of metrics (raw/json/tsv/htsv/csv/hcsv).",
+        metavar="<type>",
     )
     metrics_modify_parser.add_argument(
-        "-x", "--xpath", help="json/tsv/htsv/csv/hcsv path."
+        "-x", "--xpath", help="json/tsv/htsv/csv/hcsv path.", metavar="<path>",
     )
     metrics_modify_parser.add_argument("path", help="Path to a metric file.")
     metrics_modify_parser.set_defaults(func=CmdMetricsModify)
@@ -303,6 +310,7 @@ def add_parser(subparsers, parent_parser):
             "Metric files or directories (see -R) to show diff for. "
             "Shows diff for all metric files by default."
         ),
+        metavar="<paths>",
     )
     metrics_diff_parser.add_argument(
         "-t",
@@ -312,9 +320,10 @@ def add_parser(subparsers, parent_parser):
             "It can be detected by the file extension automatically. "
             "Unsupported types will be treated as raw."
         ),
+        metavar="<type>",
     )
     metrics_diff_parser.add_argument(
-        "-x", "--xpath", help="json/tsv/htsv/csv/hcsv path."
+        "-x", "--xpath", help="json/tsv/htsv/csv/hcsv path.", metavar="<path>",
     )
     metrics_diff_parser.add_argument(
         "-R",
diff --git a/dvc/command/repro.py b/dvc/command/repro.py
@@ -92,6 +92,7 @@ def add_parser(subparsers, parent_parser):
         "--cwd",
         default=os.path.curdir,
         help="Directory within your repo to reproduce from.",
+        metavar="<path>",
     )
     repro_parser.add_argument(
         "-m",
diff --git a/dvc/command/run.py b/dvc/command/run.py
@@ -95,13 +95,15 @@ def add_parser(subparsers, parent_parser):
         action="append",
         default=[],
         help="Declare dependencies for reproducible cmd.",
+        metavar="<path>",
     )
     run_parser.add_argument(
         "-o",
         "--outs",
         action="append",
         default=[],
         help="Declare output file or directory.",
+        metavar="<filename>",
     )
     run_parser.add_argument(
         "-O",
@@ -110,20 +112,23 @@ def add_parser(subparsers, parent_parser):
         default=[],
         help="Declare output file or directory "
         "(do not put into DVC cache).",
+        metavar="<filename>",
     )
     run_parser.add_argument(
         "-p",
         "--params",
         action="append",
         default=[],
         help="Declare parameter to use as additional dependency.",
+        metavar="[<filename>:]<params_list>",
     )
     run_parser.add_argument(
         "-m",
         "--metrics",
         action="append",
         default=[],
         help="Declare output metric file or directory.",
+        metavar="<path>",
     )
     run_parser.add_argument(
         "-M",
@@ -132,14 +137,19 @@ def add_parser(subparsers, parent_parser):
         default=[],
         help="Declare output metric file or directory "
         "(do not put into DVC cache).",
+        metavar="<path>",
     )
     run_parser.add_argument(
-        "-f", "--file", help="Specify name of the DVC-file it generates."
+        "-f",
+        "--file",
+        help="Specify name of the DVC-file this command will generate.",
+        metavar="<filename>",
     )
     run_parser.add_argument(
         "-w",
         "--wdir",
         help="Directory within your repo to run your command in.",
+        metavar="<path>",
     )
     run_parser.add_argument(
         "--no-exec",
@@ -179,13 +189,15 @@ def add_parser(subparsers, parent_parser):
         default=[],
         help="Declare output file or directory that will not be "
         "removed upon repro.",
+        metavar="<filename>",
     )
     run_parser.add_argument(
         "--outs-persist-no-cache",
         action="append",
         default=[],
         help="Declare output file or directory that will not be "
         "removed upon repro (do not put into DVC cache).",
+        metavar="<filename>",
     )
     run_parser.add_argument(
         "--always-changed",
diff --git a/dvc/command/update.py b/dvc/command/update.py
@@ -34,6 +34,9 @@ def add_parser(subparsers, parent_parser):
         "targets", nargs="+", help="DVC-files to update."
     )
     update_parser.add_argument(
-        "--rev", nargs="?", help="Git revision (e.g. SHA, branch, tag)"
+        "--rev",
+        nargs="?",
+        help="Git revision (e.g. SHA, branch, tag)",
+        metavar="<commit>",
     )
     update_parser.set_defaults(func=CmdUpdate)

Original file line number	Diff line number	Diff line change
`@@ -89,7 +89,11 @@ def shared_parent_parser():`
`89`	`89`	`add_help=False, parents=[get_parent_parser()]`
`90`	`90`	`)`
`91`	`91`	`shared_parent_parser.add_argument(`
`92`		`- "-j", "--jobs", type=int, help="Number of jobs to run simultaneously."`
	`92`	`+ "-j",`
	`93`	`+ "--jobs",`
	`94`	`+ type=int,`
	`95`	`+ help="Number of jobs to run simultaneously.",`
	`96`	`+ metavar="<number>",`
`93`	`97`	`)`
`94`	`98`	`shared_parent_parser.add_argument(`
`95`	`99`	`"targets",`
`@@ -115,7 +119,7 @@ def add_parser(subparsers, _parent_parser):`
`115`	`119`	`formatter_class=argparse.RawDescriptionHelpFormatter,`
`116`	`120`	`)`
`117`	`121`	`pull_parser.add_argument(`
`118`		`- "-r", "--remote", help="Remote repository to pull from."`
	`122`	`+ "-r", "--remote", help="Remote storage to pull from", metavar="<name>",`
`119`	`123`	`)`
`120`	`124`	`pull_parser.add_argument(`
`121`	`125`	`"-a",`
`@@ -171,7 +175,7 @@ def add_parser(subparsers, _parent_parser):`
`171`	`175`	`formatter_class=argparse.RawDescriptionHelpFormatter,`
`172`	`176`	`)`
`173`	`177`	`push_parser.add_argument(`
`174`		`- "-r", "--remote", help="Remote repository to push to."`
	`178`	`+ "-r", "--remote", help="Remote storage to push to", metavar="<name>",`
`175`	`179`	`)`
`176`	`180`	`push_parser.add_argument(`
`177`	`181`	`"-a",`
`@@ -223,7 +227,10 @@ def add_parser(subparsers, _parent_parser):`
`223`	`227`	`formatter_class=argparse.RawDescriptionHelpFormatter,`
`224`	`228`	`)`
`225`	`229`	`fetch_parser.add_argument(`
`226`		`- "-r", "--remote", help="Remote repository to fetch from."`
	`230`	`+ "-r",`
	`231`	`+ "--remote",`
	`232`	`+ help="Remote storage to fetch from",`
	`233`	`+ metavar="<name>",`
`227`	`234`	`)`
`228`	`235`	`fetch_parser.add_argument(`
`229`	`236`	`"-a",`
`@@ -292,7 +299,10 @@ def add_parser(subparsers, _parent_parser):`
`292`	`299`	`help="Show status of a local cache compared to a remote repository.",`
`293`	`300`	`)`
`294`	`301`	`status_parser.add_argument(`
`295`		`- "-r", "--remote", help="Remote repository to compare local cache to."`
	`302`	`+ "-r",`
	`303`	`+ "--remote",`
	`304`	`+ help="Remote storage to compare local cache to",`
	`305`	`+ metavar="<name>",`
`296`	`306`	`)`
`297`	`307`	`status_parser.add_argument(`
`298`	`308`	`"-a",`
Original file line number	Diff line number	Diff line change
`@@ -48,9 +48,16 @@ def add_parser(subparsers, parent_parser):`
`48`	`48`	`"path", help="Path to a file or directory within the repository"`
`49`	`49`	`)`
`50`	`50`	`import_parser.add_argument(`
`51`		`- "-o", "--out", nargs="?", help="Destination path to download files to"`
	`51`	`+ "-o",`
	`52`	`+ "--out",`
	`53`	`+ nargs="?",`
	`54`	`+ help="Destination path to download files to",`
	`55`	`+ metavar="<path>",`
`52`	`56`	`)`
`53`	`57`	`import_parser.add_argument(`
`54`		`- "--rev", nargs="?", help="Git revision (e.g. SHA, branch, tag)"`
	`58`	`+ "--rev",`
	`59`	`+ nargs="?",`
	`60`	`+ help="Git revision (e.g. SHA, branch, tag)",`
	`61`	`+ metavar="<commit>",`
`55`	`62`	`)`
`56`	`63`	`import_parser.set_defaults(func=CmdImport)`
Original file line number	Diff line number	Diff line change
`@@ -59,6 +59,9 @@ def add_parser(subparsers, parent_parser):`
`59`	`59`	`"out", nargs="?", help="Destination path to put files to."`
`60`	`60`	`)`
`61`	`61`	`import_parser.add_argument(`
`62`		`- "-f", "--file", help="Specify name of the DVC-file it generates."`
	`62`	`+ "-f",`
	`63`	`+ "--file",`
	`64`	`+ help="Specify name of the DVC-file this command will generate.",`
	`65`	`+ metavar="<filename>",`
`63`	`66`	`)`
`64`	`67`	`import_parser.set_defaults(func=CmdImportUrl)`
Original file line number	Diff line number	Diff line change
`@@ -67,7 +67,10 @@ def add_parser(subparsers, parent_parser):`
`67`	`67`	`"--outs-only", action="store_true", help="Show only DVC outputs."`
`68`	`68`	`)`
`69`	`69`	`list_parser.add_argument(`
`70`		`- "--rev", nargs="?", help="Git revision (e.g. branch, tag, SHA)"`
	`70`	`+ "--rev",`
	`71`	`+ nargs="?",`
	`72`	`+ help="Git revision (e.g. SHA, branch, tag)",`
	`73`	`+ metavar="<commit>",`
`71`	`74`	`)`
`72`	`75`	`list_parser.add_argument(`
`73`	`76`	`"path",`
Original file line number	Diff line number	Diff line change
`@@ -92,6 +92,7 @@ def add_parser(subparsers, parent_parser):`
`92`	`92`	`"--cwd",`
`93`	`93`	`default=os.path.curdir,`
`94`	`94`	`help="Directory within your repo to reproduce from.",`
	`95`	`+ metavar="<path>",`
`95`	`96`	`)`
`96`	`97`	`repro_parser.add_argument(`
`97`	`98`	`"-m",`
Original file line number	Diff line number	Diff line change
`@@ -34,6 +34,9 @@ def add_parser(subparsers, parent_parser):`
`34`	`34`	`"targets", nargs="+", help="DVC-files to update."`
`35`	`35`	`)`
`36`	`36`	`update_parser.add_argument(`
`37`		`- "--rev", nargs="?", help="Git revision (e.g. SHA, branch, tag)"`
	`37`	`+ "--rev",`
	`38`	`+ nargs="?",`
	`39`	`+ help="Git revision (e.g. SHA, branch, tag)",`
	`40`	`+ metavar="<commit>",`
`38`	`41`	`)`
`39`	`42`	`update_parser.set_defaults(func=CmdUpdate)`