run: hide and forbid --file for multistage files

dvc/command/run.py

@@ -159,9 +159,7 @@ def add_parser(subparsers, parent_parser):
         metavar="<path>",
     )
     run_parser.add_argument(
-        "--file",
-        help="Specify name of the DVC-file this command will generate.",
-        metavar="<filename>",
+        "--file", metavar="<filename>", help=argparse.SUPPRESS,
     )
     run_parser.add_argument(
         "-w",

dvc/repo/run.py

@@ -91,6 +91,12 @@ def run(self, fname=None, no_exec=False, single_stage=False, **kwargs):
             "`-n|--name` is incompatible with `--single-stage`"
         )
 
+    if stage_name and fname:
+        raise InvalidArgumentError(
+            "`--file` is currently incompatible with `-n|--name` "
+            "and requires `--single-stage`"
+        )
+
     if not stage_name and not single_stage:
         raise InvalidArgumentError("`-n|--name` is required")
 

tests/unit/repo/test_run.py

@@ -0,0 +1,12 @@
+import pytest
+
+from dvc.exceptions import InvalidArgumentError
+
+
+def test_file(tmp_dir, dvc):
+    msg = (
+        "`--file` is currently incompatible with `-n|--name` "
+        "and requires `--single-stage`"
+    )
+    with pytest.raises(InvalidArgumentError, match=msg):
+        dvc.run(fname="path/dvc.yaml", name="my", cmd="mycmd")