A sketch for more formalised but CLI output handling.

Author: Byron

Cargo.lock

@@ -51,8 +51,13 @@ pub fn git_at_dir(dir: impl AsRef<Path>) -> std::process::Command {
 /// Run the given `script` in bash, with the `cwd` set to the `repo` worktree.
 /// Panic if the script fails.
 pub fn invoke_bash(script: &str, repo: &gix::Repository) {
+    invoke_bash_at_dir(script, repo.workdir().unwrap_or(repo.git_dir()))
+}
+/// Run the given `script` in bash, with the `cwd` set to `dir`.
+/// Panic if the script fails.
+pub fn invoke_bash_at_dir(script: &str, dir: &Path) {
     let mut cmd = std::process::Command::new("bash");
-    cmd.current_dir(repo.workdir().unwrap_or(repo.git_dir()));
+    cmd.current_dir(dir);
     isolate_env_std_cmd(&mut cmd);
     cmd.stdin(std::process::Stdio::piped())
         .stdout(std::process::Stdio::piped())

crates/but-testsupport/src/lib.rs

@@ -80,6 +80,7 @@ cli-prompts = "0.1.0"
 
 [dev-dependencies]
 but-core = { workspace = true, features = ["testing"] }
+serde_json = { workspace = true, features = ["preserve_order"] }
 but-testsupport = { workspace = true, features = ["snapbox"] }
 snapbox = { workspace = true, features = ["term-svg", "regex"] }
 shell-words = "1.1.0"

crates/but/Cargo.toml

@@ -11,6 +11,11 @@ pub struct Args {
     /// Run as if gitbutler-cli was started in PATH instead of the current working directory.
     #[clap(short = 'C', long, default_value = ".", value_name = "PATH")]
     pub current_dir: PathBuf,
+    /// Explicitly control how output should be formatted.
+    ///
+    /// If unset and from a terminal, it defaults to human output, when redirected it's for shells.
+    #[clap(long, short = 'f', env = "BUT_OUTPUT_FORMAT", conflicts_with = "json")]
+    pub format: Option<OutputFormat>,
     /// Whether to use JSON output format.
     #[clap(long, short = 'j', global = true)]
     pub json: bool,
@@ -198,6 +203,18 @@ For examples see `but rub --help`."
     },
 }
 
+/// How to format the output.
+#[derive(Debug, Clone, Copy, clap::ValueEnum, Default)]
+pub enum OutputFormat {
+    /// Produce verbose output for human consumption.
+    #[default]
+    Human,
+    /// The output is optimised for variable assignment in shells.
+    Shell,
+    /// Output detailed information as JSON for tool consumption.
+    Json,
+}
+
 #[derive(Debug, Clone, Copy, clap::ValueEnum, Default)]
 pub enum CommandName {
     #[clap(alias = "log")]

crates/but/src/args.rs

@@ -1,6 +1,9 @@
+use crate::utils::{Output, OutputFormat};
 use anyhow::bail;
 use bstr::ByteSlice;
 use gitbutler_reference::RemoteRefname;
+use gix::reference::Category;
+use std::io::Write;
 use std::{ops::Deref, str::FromStr};
 
 /// Apply a branch to the workspace, and return the full ref name to it.
@@ -9,7 +12,7 @@ use std::{ops::Deref, str::FromStr};
 pub fn apply(
     ctx: &but_ctx::Context,
     branch_name: &str,
-    json: bool,
+    out: &mut Output,
 ) -> anyhow::Result<but_api::json::Reference> {
     let legacy_project = &ctx.legacy_project;
     let ctx = ctx.legacy_ctx()?;
@@ -32,9 +35,6 @@ pub fn apply(
             remote_ref_name,
             None,
         )?;
-        if !json {
-            println!("Applied branch '{branch_name}' to workspace");
-        }
         reference
     } else if let Some((remote_ref, reference)) = find_remote_reference(&repo, branch_name)? {
         let remote = remote_ref.remote();
@@ -48,14 +48,30 @@ pub fn apply(
             Some(remote_ref.clone()),
             None,
         )?;
-        if !json {
-            println!("Applied remote branch '{branch_name}' to workspace");
-        }
         reference
     } else {
         bail!("Could not find branch '{branch_name}' in local repository");
     };
 
+    match out.format {
+        OutputFormat::Human => {
+            let short_name = reference.name().shorten();
+            let is_remote_reference = reference
+                .name()
+                .category()
+                .is_some_and(|c| c == Category::RemoteBranch);
+            if is_remote_reference {
+                writeln!(out, "Applied remote branch '{short_name}' to workspace")
+            } else {
+                writeln!(out, "Applied branch '{short_name}' to workspace")
+            }
+            .ok();
+        }
+        OutputFormat::Shell => {
+            writeln!(out, "{reference_name}", reference_name = reference.name())?;
+        }
+    }
+
     Ok(reference.inner.into())
 }
 

crates/but/src/branch/apply.rs

@@ -1,6 +1,6 @@
 use std::io::Write;
 
-use crate::we_need_proper_json_output_here;
+use crate::utils::we_need_proper_json_output_here;
 use colored::Colorize;
 use gitbutler_branch_actions::BranchListingFilter;
 use gitbutler_project::Project;

crates/but/src/branch/list.rs

@@ -1,6 +1,6 @@
-use crate::{LegacyProject, into_json_value, we_need_proper_json_output_here};
+use crate::LegacyProject;
+use crate::utils::{Output, OutputFormat, into_json_value, we_need_proper_json_output_here};
 use anyhow::bail;
-use atty::Stream;
 use but_core::ref_metadata::StackId;
 use but_settings::AppSettings;
 use but_workspace::legacy::ui::StackEntry;
@@ -70,9 +70,8 @@ pub enum Subcommands {
 pub async fn handle(
     cmd: Option<Subcommands>,
     ctx: &but_ctx::Context,
-    json: bool,
+    out: &mut Output,
 ) -> anyhow::Result<serde_json::Value> {
-    let mut stdout = io::stdout();
     let legacy_project = &ctx.legacy_project;
     match cmd {
         None => {
@@ -147,18 +146,19 @@ pub async fn handle(
                 },
             )?;
 
-            if json {
-                let response = json::BranchNewOutput {
-                    branch: branch_name,
-                    anchor: anchor_for_json,
-                };
-                writeln!(stdout, "{}", serde_json::to_string_pretty(&response)?)?;
-            } else if atty::is(Stream::Stdout) {
-                writeln!(stdout, "Created branch {branch_name}").ok();
-            } else {
-                writeln!(stdout, "{branch_name}").ok();
+            let json = json::BranchNewOutput {
+                branch: branch_name.clone(),
+                anchor: anchor_for_json,
+            };
+            match out.format {
+                OutputFormat::Human => {
+                    writeln!(out, "Created branch {branch_name}").ok();
+                }
+                OutputFormat::Shell => {
+                    writeln!(out, "{branch_name}").ok();
+                }
             }
-            Ok(we_need_proper_json_output_here())
+            Ok(into_json_value(json))
         }
         Some(Subcommands::Delete { branch_name, force }) => {
             let stacks = but_api::workspace::stacks(
@@ -178,11 +178,11 @@ pub async fn handle(
                 }
             }
 
-            writeln!(stdout, "Branch '{}' not found in any stack", branch_name).ok();
+            writeln!(out, "Branch '{}' not found in any stack", branch_name).ok();
             Ok(we_need_proper_json_output_here())
         }
         Some(Subcommands::Apply { branch_name }) => {
-            apply::apply(ctx, &branch_name, json).map(into_json_value)
+            apply::apply(ctx, &branch_name, out).map(into_json_value)
         }
         Some(Subcommands::Unapply { branch_name, force }) => {
             let stacks = but_api::workspace::stacks(
@@ -202,7 +202,7 @@ pub async fn handle(
                 }
             }
 
-            writeln!(stdout, "Branch '{}' not found in any stack", branch_name).ok();
+            writeln!(out, "Branch '{}' not found in any stack", branch_name).ok();
             Ok(we_need_proper_json_output_here())
         }
     }