diff --git a/docs/global_options.rst b/docs/global_options.rst
index 975eabf5..e3bf6f01 100644
--- a/docs/global_options.rst
+++ b/docs/global_options.rst
@@ -175,7 +175,7 @@ Run poe from anywhere
By default poe will detect when you're inside a project with a pyproject.toml in the
root. However if you want to run it from elsewhere then that is supported by using the
-:bash:`--root` option to specify an alternate location for the toml file. The task will
+:bash:`-C` option to specify an alternate location for the toml file. The task will
run with the given location as the current working directory.
In all cases the path to project root (where the pyproject.toml resides) will be
diff --git a/docs/guides/help_guide.rst b/docs/guides/help_guide.rst
index a2e99f30..d90be22d 100644
--- a/docs/guides/help_guide.rst
+++ b/docs/guides/help_guide.rst
@@ -23,20 +23,21 @@ This help text will be displayed alongside the task name in the list of configur
$ poe --help
Poe the Poet - A task runner that works well with poetry.
- version 0.19.0
+ version 0.25.1
USAGE
- poe [-h] [-v | -q] [--root PATH] [--ansi | --no-ansi] task [task arguments]
+ poe [-h] [-v | -q] [-C PATH] [--ansi | --no-ansi] task [task arguments]
GLOBAL OPTIONS
- -h, --help Show this help page and exit
- --version Print the version and exit
- -v, --verbose Increase command output (repeatable)
- -q, --quiet Decrease command output (repeatable)
- -d, --dry-run Print the task contents but don't actually run it
- --root PATH Specify where to find the pyproject.toml
- --ansi Force enable ANSI output
- --no-ansi Force disable ANSI output
+ -h, --help Show this help page and exit
+ --version Print the version and exit
+ -v, --verbose Increase command output (repeatable)
+ -q, --quiet Decrease command output (repeatable)
+ -d, --dry-run Print the task contents but don't actually run it
+ -C PATH, --directory PATH
+ Specify where to find the pyproject.toml
+ --ansi Force enable ANSI output
+ --no-ansi Force disable ANSI output
CONFIGURED TASKS
test Run the test suite
diff --git a/docs/index.rst b/docs/index.rst
index 0b1db16f..0c0b2eea 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -117,7 +117,7 @@ If no virtualenv is found then poe will run tasks without any special environmen
Run poe from anywhere
=====================
-By default poe will detect when you're inside a project with a pyproject.toml in the root. However if you want to run it from elsewhere then that is supported by using the :sh:`--root` option to specify an alternate location for the toml file. The task will run with the given location as the current working directory.
+By default poe will detect when you're inside a project with a pyproject.toml in the root. However if you want to run it from elsewhere then that is supported by using the :sh:`-C` option to specify an alternate location for the toml file. The task will run with the given location as the current working directory.
In all cases the path to project root (where the pyproject.toml resides) will be available as :sh:`$POE_ROOT` within the command line and process. The variable :sh:`$POE_PWD` contains the original working directory from which poe was run.
diff --git a/poethepoet/ui.py b/poethepoet/ui.py
index e22b109e..b9693a6d 100644
--- a/poethepoet/ui.py
+++ b/poethepoet/ui.py
@@ -114,7 +114,8 @@ def build_parser(self) -> "ArgumentParser":
)
parser.add_argument(
- "--root",
+ "-C",
+ "--directory",
dest="project_root",
metavar="PATH",
type=str,
@@ -122,6 +123,17 @@ def build_parser(self) -> "ArgumentParser":
help="Specify where to find the pyproject.toml",
)
+ # legacy --root parameter, keep for backwards compatability but help output is
+ # suppressed
+ parser.add_argument(
+ "--root",
+ dest="project_root",
+ metavar="PATH",
+ type=str,
+ default=None,
+ help=argparse.SUPPRESS,
+ )
+
ansi_group = parser.add_mutually_exclusive_group()
ansi_group.add_argument(
"--ansi",
@@ -206,7 +218,7 @@ def print_help(
(
"
USAGE
",
f" {self.program_name}"
- " [-h] [-v | -q] [--root PATH] [--ansi | --no-ansi]"
+ " [-h] [-v | -q] [-C PATH] [--ansi | --no-ansi]"
" task [task arguments]",
)
)
diff --git a/tests/test_api.py b/tests/test_api.py
index 8180a0ad..e34a782d 100644
--- a/tests/test_api.py
+++ b/tests/test_api.py
@@ -33,7 +33,7 @@ def test_customize_config_name_with_json(run_poe, projects, capsys):
assert result.stderr == ""
result = run_poe(
- "--root",
+ "-C",
str(projects["custom_config"]),
"hello",
config_name="tasks.json",
diff --git a/tests/test_cli.py b/tests/test_cli.py
index 2d0636a1..50a8c1fe 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -15,6 +15,22 @@ def test_call_no_args(run_poe):
assert "CONFIGURED TASKS\n echo" in result.capture, "echo task should be in help"
+def test_call_with_directory(run_poe, projects):
+ result = run_poe("--directory", str(projects["example"]), cwd=".")
+ assert result.code == 1, "Expected non-zero result"
+ assert result.capture.startswith(
+ "Poe the Poet - A task runner that works well with poetry."
+ ), "Output should start with poe header line"
+ assert (
+ "\nResult: No task specified.\n" in result.capture
+ ), "Output should include status message"
+ assert (
+ "CONFIGURED TASKS\n echo It says what you say"
+ in result.capture
+ ), "echo task should be in help"
+
+
+# Test legacy --root parameter (replaced by -C, --directory)
def test_call_with_root(run_poe, projects):
result = run_poe("--root", str(projects["example"]), cwd=".")
assert result.code == 1, "Expected non-zero result"
diff --git a/tests/test_cmd_tasks.py b/tests/test_cmd_tasks.py
index 37f1cd0d..6ebef933 100644
--- a/tests/test_cmd_tasks.py
+++ b/tests/test_cmd_tasks.py
@@ -173,7 +173,7 @@ def test_cmd_task_with_with_glob_arg_and_cwd(
def test_cmd_with_capture_stdout(run_poe_subproc, projects, poe_project_path):
result = run_poe_subproc(
- "--root",
+ "-C",
str(projects["cmds"]),
"meeseeks",
project="cmds",
diff --git a/tests/test_envfile.py b/tests/test_envfile.py
index 5bb32be5..9be3c62e 100644
--- a/tests/test_envfile.py
+++ b/tests/test_envfile.py
@@ -20,7 +20,7 @@ def test_task_envfile_and_default(run_poe_subproc):
def test_multiple_envfiles(run_poe_subproc, projects):
result = run_poe_subproc(
- f'--root={projects["envfile/multiple_envfiles"]}', "show_me_the_vals"
+ f'-C={projects["envfile/multiple_envfiles"]}', "show_me_the_vals"
)
assert (
diff --git a/tests/test_includes.py b/tests/test_includes.py
index 17d9909d..3e4ba44a 100644
--- a/tests/test_includes.py
+++ b/tests/test_includes.py
@@ -27,7 +27,7 @@ def test_run_task_not_included_from_toml_file(run_poe_subproc):
def test_docs_for_multiple_includes(run_poe_subproc, projects):
result = run_poe_subproc(
- f'--root={projects["includes/multiple_includes"]}',
+ f'-C={projects["includes/multiple_includes"]}',
)
assert (
"CONFIGURED TASKS\n"
@@ -44,7 +44,7 @@ def test_docs_for_multiple_includes(run_poe_subproc, projects):
def test_running_from_multiple_includes(run_poe_subproc, projects):
result = run_poe_subproc(
- f'--root={projects["includes/multiple_includes"]}',
+ f'-C={projects["includes/multiple_includes"]}',
"echo",
"Whirl!",
project="includes",
@@ -54,15 +54,13 @@ def test_running_from_multiple_includes(run_poe_subproc, projects):
assert result.stderr == ""
result = run_poe_subproc(
- f'--root={projects["includes/multiple_includes"]}', "greet", "Whirl!"
+ f'-C={projects["includes/multiple_includes"]}', "greet", "Whirl!"
)
assert result.capture == "Poe => poe_test_echo Hello 'Whirl!'\n"
assert result.stdout == "Hello Whirl!\n"
assert result.stderr == ""
- result = run_poe_subproc(
- f'--root={projects["includes/multiple_includes"]}', "laugh"
- )
+ result = run_poe_subproc(f'-C={projects["includes/multiple_includes"]}', "laugh")
assert result.capture == "Poe => poe_test_echo $ONE_LAUGH | tr a-z A-Z\n"
assert result.stdout == "LOL\n"
assert result.stderr == ""
@@ -70,7 +68,7 @@ def test_running_from_multiple_includes(run_poe_subproc, projects):
def test_reference_peer_include(run_poe_subproc, projects):
result = run_poe_subproc(
- f'--root={projects["includes/multiple_includes"]}', "reference_peer_include"
+ f'-C={projects["includes/multiple_includes"]}', "reference_peer_include"
)
assert (
result.capture
@@ -82,7 +80,7 @@ def test_reference_peer_include(run_poe_subproc, projects):
def test_docs_for_only_includes(run_poe_subproc, projects):
result = run_poe_subproc(
- f'--root={projects["includes/only_includes"]}',
+ f'-C={projects["includes/only_includes"]}',
)
assert (
"CONFIGURED TASKS\n"
@@ -171,7 +169,7 @@ def test_monorepo_runs_each_task_with_expected_cwd(
assert result.stderr == ""
result = run_poe_subproc(
- "--root",
+ "-C",
str(projects["monorepo/subproject_3"]),
"get_cwd_3",
cwd=projects["example"],
diff --git a/tests/test_script_tasks.py b/tests/test_script_tasks.py
index cbd9e372..9f694aea 100644
--- a/tests/test_script_tasks.py
+++ b/tests/test_script_tasks.py
@@ -207,7 +207,7 @@ def test_required_args(run_poe_subproc):
def test_script_task_bad_type(run_poe_subproc, projects):
result = run_poe_subproc(
- f'--root={projects["scripts/bad_type"]}',
+ f'-C={projects["scripts/bad_type"]}',
"bad-type",
"--greeting=hello",
)
@@ -223,7 +223,7 @@ def test_script_task_bad_type(run_poe_subproc, projects):
def test_script_task_bad_content(run_poe_subproc, projects):
result = run_poe_subproc(
- f'--root={projects["scripts/bad_content"]}',
+ f'-C={projects["scripts/bad_content"]}',
"bad-content",
"--greeting=hello",
)
diff --git a/tests/test_shell_task.py b/tests/test_shell_task.py
index 8ab90456..fdf80f35 100644
--- a/tests/test_shell_task.py
+++ b/tests/test_shell_task.py
@@ -93,7 +93,7 @@ def test_interpreter_python(run_poe_subproc):
def test_bad_interpreter_config(run_poe_subproc, projects):
result = run_poe_subproc(
- f'--root={projects["shells/bad_interpreter"]}',
+ f'-C={projects["shells/bad_interpreter"]}',
"bad-interpreter",
)
assert (
@@ -108,7 +108,7 @@ def test_bad_interpreter_config(run_poe_subproc, projects):
def test_global_interpreter_config(run_poe_subproc, projects):
result = run_poe_subproc(
- f'--root={projects["shells/shell_interpreter_config"]}',
+ f'-C={projects["shells/shell_interpreter_config"]}',
"echo_python",
)
assert result.capture == "Poe => import sys\nprint(sys.version_info)\n"