Provide porcelain output for scripts.

Options:
* local branches
* remote branches
* JSON output.

\foriequal0#138

.prettierrc

@@ -0,0 +1 @@
+{ "proseWrap": "always", "tabWidth": 4 }

CHANGELOG.md

@@ -3,7 +3,8 @@
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Types of Change
 
@@ -16,6 +17,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+-   `--porcelain` option to provide output for scripting without deleting any
+    branches. Options are `local`, `remote` or `json`. Those list local branches
+    that should be deleted, remote branches or all output in structured JSON.
+    The JSON can be further filtered with _jq_ or _gron_.
+
 ### Changed
 
--   Performance increase for big repos. Associating each local branch with all remotes is now multiple orders of magnitude faster. There are still bottlenecks that make the use on big repos impractically slow.
+-   Performance increase for big repos. Associating each local branch with all
+    remotes is now multiple orders of magnitude faster. There are still
+    bottlenecks that make the use on big repos impractically slow.

Cargo.toml

@@ -41,6 +41,8 @@ man = { version = "0.3.0", optional = true }
 rson_rs = { version = "0.2.1", optional = true }
 regex = { version = "1.4.2", optional = true }
 indicatif = { version = "0.15.0" , features = ["rayon"]}
+serde =  { version = "1.0.117", features = ["derive"] }
+serde_json = "1.0.59"
 
 [dev-dependencies]
 tempfile = "3.1.0"

src/args.rs

@@ -40,6 +40,10 @@ pub struct Args {
     #[clap(long, hidden(true))]
     pub update: bool,
 
+    /// Output for scripting. Options are "json" for full structured output or "local" or "remote" for a list of branches to be deleted.
+    #[clap(long)]
+    pub porcelain: Option<PorcelainFormat>,
+
     /// Prevents too frequent updates. Seconds between updates in seconds. 0 to disable.
     /// [default: 5] [config: trim.updateInterval]
     #[clap(long)]
@@ -127,6 +131,41 @@ fn exclusive_bool(
     }
 }
 
+/// Configuration of --porcelain format.
+#[derive(Debug)]
+pub enum PorcelainFormat {
+    /// List of to-be-deleted local branches
+    LocalBranches,
+    /// List of remote branches to be deleted.
+    RemoteBranches,
+    /// Full structured JSON output
+    JSON,
+}
+
+impl FromStr for PorcelainFormat {
+    type Err = PorcelainFormatParseError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s.trim() {
+            "" => Err(PorcelainFormatParseError {
+                message: "Porcelain format is empty".to_owned(),
+            }),
+            "json" => Ok(PorcelainFormat::JSON),
+            "local" | "l" => Ok(PorcelainFormat::LocalBranches),
+            "remote" | "r" => Ok(PorcelainFormat::RemoteBranches),
+            unknown => Err(PorcelainFormatParseError {
+                message: format!("Unknown porcelain format: {}", unknown),
+            }),
+        }
+    }
+}
+
+#[derive(Error, Debug)]
+#[error("{message}")]
+pub struct PorcelainFormatParseError {
+    message: String,
+}
+
 #[derive(Hash, Eq, PartialEq, Clone, Debug)]
 pub enum Scope {
     All,

src/branch.rs

@@ -3,6 +3,7 @@ use std::convert::TryFrom;
 use anyhow::{Context, Result};
 use git2::{Branch, Config, Direction, Reference, Repository};
 use log::*;
+use serde::Serialize;
 use thiserror::Error;
 
 use crate::config;
@@ -12,7 +13,7 @@ pub trait Refname {
     fn refname(&self) -> &str;
 }
 
-#[derive(Eq, PartialEq, Ord, PartialOrd, Debug, Hash, Clone)]
+#[derive(Eq, PartialEq, Ord, PartialOrd, Debug, Hash, Clone, Serialize)]
 pub struct LocalBranch {
     pub refname: String,
 }
@@ -83,7 +84,7 @@ impl<'repo> TryFrom<&git2::Reference<'repo>> for LocalBranch {
     }
 }
 
-#[derive(Eq, PartialEq, Ord, PartialOrd, Debug, Hash, Clone)]
+#[derive(Eq, PartialEq, Ord, PartialOrd, Debug, Hash, Clone, Serialize)]
 pub struct RemoteTrackingBranch {
     pub refname: String,
 }
@@ -202,7 +203,7 @@ pub enum RemoteTrackingBranchStatus {
     None,
 }
 
-#[derive(Eq, PartialEq, Ord, PartialOrd, Clone, Hash, Debug)]
+#[derive(Eq, PartialEq, Ord, PartialOrd, Clone, Hash, Debug, Serialize)]
 pub struct RemoteBranch {
     pub remote: String,
     pub refname: String,

src/core.rs

@@ -6,6 +6,7 @@ use anyhow::{Context, Result};
 use git2::{BranchType, Config, Repository};
 use log::*;
 use rayon::prelude::*;
+use serde::Serialize;
 
 use crate::args::DeleteFilter;
 use crate::branch::{
@@ -19,12 +20,14 @@ use crate::{config, BaseSpec, Git};
 use indicatif::ParallelProgressIterator;
 use rayon::iter::ParallelIterator;
 
+#[derive(Serialize)]
 pub struct TrimPlan {
     pub skipped: HashMap<String, SkipSuggestion>,
     pub to_delete: HashSet<ClassifiedBranch>,
     pub preserved: Vec<Preserved>,
 }
 
+#[derive(Serialize)]
 pub struct Preserved {
     pub branch: ClassifiedBranch,
     pub reason: String,
@@ -392,7 +395,7 @@ impl TrimPlan {
     }
 }
 
-#[derive(Clone, Eq, PartialEq)]
+#[derive(Clone, Eq, PartialEq, Serialize)]
 pub enum SkipSuggestion {
     Tracking,
     TrackingRemote(String),
@@ -436,7 +439,7 @@ fn get_protect_pattern<'a, B: Refname>(
     Ok(None)
 }
 
-#[derive(Hash, Eq, PartialEq, Debug, Clone)]
+#[derive(Hash, Eq, PartialEq, Debug, Clone, Serialize)]
 pub enum ClassifiedBranch {
     MergedLocal(LocalBranch),
     Stray(LocalBranch),

src/lib.rs

@@ -3,6 +3,7 @@ mod branch;
 pub mod config;
 mod core;
 mod merge_tracker;
+pub mod porcelain_outputs;
 mod simple_glob;
 mod subprocess;
 mod util;

src/main.rs

@@ -9,8 +9,9 @@ use dialoguer::Confirm;
 use git2::{BranchType, Repository};
 use log::*;
 
-use git_trim::args::Args;
+use git_trim::args::{Args, PorcelainFormat};
 use git_trim::config::{self, get, Config, ConfigValue};
+use git_trim::porcelain_outputs::{print_json, print_local, print_remote};
 use git_trim::{
     delete_local_branches, delete_remote_branches, get_trim_plan, ls_remote_head, remote_update,
     ClassifiedBranch, ForceSendSync, Git, LocalBranch, PlanParam, RemoteHead, RemoteTrackingBranch,
@@ -58,7 +59,23 @@ fn main(args: Args) -> Result<()> {
         },
     )?;
 
-    print_summary(&plan, &git.repo)?;
+    match args.porcelain {
+        None => {
+            print_summary(&plan, &git.repo)?;
+        }
+        Some(PorcelainFormat::LocalBranches) => {
+            print_local(&plan, &git.repo, &mut std::io::stdout())?;
+            return Ok(());
+        }
+        Some(PorcelainFormat::RemoteBranches) => {
+            print_remote(&plan, &git.repo, &mut std::io::stdout())?;
+            return Ok(());
+        }
+        Some(PorcelainFormat::JSON) => {
+            print_json(&plan, &git.repo, &mut std::io::stdout())?;
+            return Ok(());
+        }
+    }
 
     let locals = plan.locals_to_delete();
     let remotes = plan.remotes_to_delete(&git.repo)?;

src/porcelain_outputs.rs

@@ -0,0 +1,53 @@
+use anyhow::Result;
+use git2::Repository;
+
+use crate::TrimPlan;
+
+/// Prints all locally to-be-deleted branches.
+pub fn print_local(
+    plan: &TrimPlan,
+    _repo: &Repository,
+    mut writer: impl std::io::Write,
+) -> Result<()> {
+    let mut merged_locals = Vec::new();
+    for branch in &plan.to_delete {
+        if let Some(local) = branch.local() {
+            merged_locals.push(local.short_name().to_owned());
+        }
+    }
+
+    merged_locals.sort();
+    for branch in merged_locals {
+        writeln!(writer, "{}", branch)?;
+    }
+
+    Ok(())
+}
+
+/// Print all remotely to-be-deleted branches in the form "<remote>/<branch_name>"
+pub fn print_remote(
+    plan: &TrimPlan,
+    repo: &Repository,
+    mut writer: impl std::io::Write,
+) -> Result<()> {
+    let mut merged_remotes = Vec::new();
+    for branch in &plan.to_delete {
+        if let Some(remote) = branch.remote(repo)? {
+            merged_remotes.push(remote);
+        }
+    }
+
+    merged_remotes.sort();
+    for branch in merged_remotes {
+        let branch_name = &branch.refname["/refs/heads".len()..];
+        writeln!(writer, "{}/{}", branch.remote, branch_name)?;
+    }
+
+    Ok(())
+}
+
+pub fn print_json(plan: &TrimPlan, _repo: &Repository, writer: impl std::io::Write) -> Result<()> {
+    serde_json::to_writer(writer, &plan)?;
+
+    Ok(())
+}