From afca96a9a5d88ece5d2e5c4e62ae3fc917c0a075 Mon Sep 17 00:00:00 2001
From: jdx <216188+jdx@users.noreply.github.com>
Date: Fri, 20 Dec 2024 10:05:48 -0600
Subject: [PATCH] docs: describe behavior of `run --output` better (#3740)

---
 docs/cli/run.md        | 6 +++++-
 docs/cli/tasks/run.md  | 6 +++++-
 mise.usage.kdl         | 6 ++++--
 src/cli/run.rs         | 8 +++++++-
 xtasks/fig/src/mise.ts | 4 ++++
 5 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/docs/cli/run.md b/docs/cli/run.md
index b1d095d4d9..137762c1f9 100644
--- a/docs/cli/run.md
+++ b/docs/cli/run.md
@@ -89,7 +89,11 @@ Don't show extra output
 
 Don't show any output except for errors
 
-### `--output <OUTPUT>`
+### `-o --output <OUTPUT>`
+
+Change how tasks information is output when running tasks
+
+- `prefix` - Print stdout/stderr by line, prefixed with the task's label - `interleave` - Print directly to stdout/stderr instead of by line - `quiet` - Don't show extra output - `silent` - Don't show any output including stdout and stderr from the task except for errors
 
 Examples:
 
diff --git a/docs/cli/tasks/run.md b/docs/cli/tasks/run.md
index dfc6bbd857..be43fc5945 100644
--- a/docs/cli/tasks/run.md
+++ b/docs/cli/tasks/run.md
@@ -103,7 +103,11 @@ Don't show extra output
 
 Don't show any output except for errors
 
-### `--output <OUTPUT>`
+### `-o --output <OUTPUT>`
+
+Change how tasks information is output when running tasks
+
+- `prefix` - Print stdout/stderr by line, prefixed with the task's label - `interleave` - Print directly to stdout/stderr instead of by line - `quiet` - Don't show extra output - `silent` - Don't show any output including stdout and stderr from the task except for errors
 
 Examples:
 
diff --git a/mise.usage.kdl b/mise.usage.kdl
index 1deb1950f3..58a10ca169 100644
--- a/mise.usage.kdl
+++ b/mise.usage.kdl
@@ -1086,7 +1086,8 @@ The name of the script will be the name of the tasks.
     }
     flag "-q --quiet" help="Don't show extra output"
     flag "-S --silent" help="Don't show any output except for errors"
-    flag "--output" {
+    flag "-o --output" help="Change how tasks information is output when running tasks" {
+        long_help "Change how tasks information is output when running tasks\n\n- `prefix` - Print stdout/stderr by line, prefixed with the task's label - `interleave` - Print directly to stdout/stderr instead of by line - `quiet` - Don't show extra output - `silent` - Don't show any output including stdout and stderr from the task except for errors"
         arg "<OUTPUT>"
     }
     mount run="mise tasks --usage"
@@ -1527,7 +1528,8 @@ The name of the script will be the name of the tasks.
         }
         flag "-q --quiet" help="Don't show extra output"
         flag "-S --silent" help="Don't show any output except for errors"
-        flag "--output" {
+        flag "-o --output" help="Change how tasks information is output when running tasks" {
+            long_help "Change how tasks information is output when running tasks\n\n- `prefix` - Print stdout/stderr by line, prefixed with the task's label - `interleave` - Print directly to stdout/stderr instead of by line - `quiet` - Don't show extra output - `silent` - Don't show any output including stdout and stderr from the task except for errors"
             arg "<OUTPUT>"
         }
         arg "[TASK]" help="Tasks to run\nCan specify multiple tasks by separating with `:::`\ne.g.: mise run task1 arg1 arg2 ::: task2 arg1 arg2" required=false default="default"
diff --git a/src/cli/run.rs b/src/cli/run.rs
index d46716e81e..90636d1b2c 100644
--- a/src/cli/run.rs
+++ b/src/cli/run.rs
@@ -166,7 +166,13 @@ pub struct Run {
     #[clap(skip)]
     pub failed_tasks: Mutex<Vec<(Task, i32)>>,
 
-    #[clap(long)]
+    /// Change how tasks information is output when running tasks
+    ///
+    /// - `prefix` - Print stdout/stderr by line, prefixed with the task's label
+    /// - `interleave` - Print directly to stdout/stderr instead of by line
+    /// - `quiet` - Don't show extra output
+    /// - `silent` - Don't show any output including stdout and stderr from the task except for errors
+    #[clap(short, long, env = "MISE_TASK_OUTPUT")]
     pub output: Option<TaskOutput>,
 
     #[clap(skip)]
diff --git a/xtasks/fig/src/mise.ts b/xtasks/fig/src/mise.ts
index 7926870a8c..e4cc014cee 100644
--- a/xtasks/fig/src/mise.ts
+++ b/xtasks/fig/src/mise.ts
@@ -2009,8 +2009,10 @@ const completionSpec: Fig.Spec = {
                 },
                 {
                     "name": [
+                        "-o",
                         "--output"
                     ],
+                    "description": "Change how tasks information is output when running tasks",
                     "isRepeatable": false,
                     "args": {
                         "name": "output",
@@ -2915,8 +2917,10 @@ const completionSpec: Fig.Spec = {
                         },
                         {
                             "name": [
+                                "-o",
                                 "--output"
                             ],
+                            "description": "Change how tasks information is output when running tasks",
                             "isRepeatable": false,
                             "args": {
                                 "name": "output",