Proper implementation of line renderer into 'lean' CLI

Byron · Byron · commit e98e7c280d73 · 2020-07-11T10:52:03.000+08:00
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -23,8 +23,11 @@ doctest = false
 
 [features]
 default = ["max"]
-max = ["fast", "pretty-cli"]
-lean = ["fast", "lean-cli", "prodash-line-renderer-crossterm", "git-features/progress-prodash"]
+max = ["fast", "pretty-cli", "prodash/tui-renderer-crossterm"]
+max-termion = ["fast", "pretty-cli", "prodash/tui-renderer-termion"]
+lean = ["fast", "lean-cli", "prodash-line-renderer-crossterm"]
+lean-termion = ["fast", "lean-cli", "prodash-line-renderer-termion"]
+light = ["fast", "lean-cli"]
 small = ["lean-cli"]
 
 fast = ["git-features/parallel", "git-features/fast-sha1"]
@@ -34,26 +37,27 @@ pretty-cli = ["structopt",
               "gitoxide-core/serde1",
               "prodash/log-renderer",
               "prodash/tui-renderer",
-              "prodash/tui-renderer-crossterm",
               "prodash/localtime",
               "env_logger",
               "smol"]
 lean-cli = ["argh", "git-features/progress-log", "env_logger"]
 
-prodash-line-renderer-crossterm = ["prodash/line-renderer", "prodash/line-renderer-crossterm"]
-prodash-line-renderer-termion = ["prodash/line-renderer", "prodash/line-renderer-termion"]
+prodash-line-renderer-crossterm = ["prodash/line-renderer", "prodash/line-renderer-crossterm", "git-features/progress-prodash", "atty", "crosstermion"]
+prodash-line-renderer-termion = ["prodash/line-renderer", "prodash/line-renderer-termion", "git-features/progress-prodash", "atty", "crosstermion"]
 
 [dependencies]
 anyhow = "1.0.31"
 
 gitoxide-core = { version = "0.1.0", path = "gitoxide-core" }
 git-features = { version = "0.1.0", path = "git-features" }
 
-structopt = { version = "0.3.14", optional = true }
-argh = { version = "0.1.3", optional = true }
-prodash = { version = "7.0.0", optional = true, default-features = false }
-smol = { version = "0.1.18", optional = true }
+structopt = { version = "0.3.14", optional = true, default-features = false }
+argh = { version = "0.1.3", optional = true, default-features = false }
+prodash = { version = "7.0.2", optional = true, default-features = false }
+smol = { version = "0.1.18", optional = true, default-features = false }
+atty = { version = "0.2.14", optional = true, default-features = false }
 env_logger = { version = "0.7.1", optional = true, default-features = false, features = ["humantime", "termcolor", "atty"] }
+crosstermion = { version = "0.1.5", optional = true, default-features = false }
 
 [profile.release]
 overflow-checks = false
diff --git a/Makefile b/Makefile
@@ -56,8 +56,11 @@ check: ## Build all code in suitable configurations
 	cargo check --all
 	cargo check --all --all-features
 	cargo check --no-default-features --features small
+	cargo check --no-default-features --features light
 	cargo check --no-default-features --features lean
+	cargo check --no-default-features --features lean-termion
 	cargo check --no-default-features --features max
+	cargo check --no-default-features --features max-termion
 	cd gitoxide-core && cargo check --all-features
 	cd git-object && cargo check --all-features
 	cd git-odb && cargo check --all-features
diff --git a/README.md b/README.md
@@ -169,19 +169,26 @@ The top-level command-line interface.
   * Makes the crate execute as fast as possible by supporting parallel computation of otherwise long-running functions
     as well as fast, hardware accelerated hashing.
   * If disabled, the binary will be visibly smaller.
-* **pretty-cli** _(default)_
-  * Use `clap` + `structopt` to build the prettiest, best documented and most user-friendly CLI at the expense of file size.
-* **lean-cli** _(mutually exclusive to pretty-cli)_
-  * Use `argh` to produce a usable binary with decent documentation that is smallest in size, usually 300kb less than `pretty-cli`.
-  * If `pretty-cli` is enabled as well, `small-cli` will take precedence, and you pay for building unnecessary dependencies.
+* _(mutually exclusive)_
+  * **pretty-cli** _(default)_
+    * Use `clap` + `structopt` to build the prettiest, best documented and most user-friendly CLI at the expense of file size.
+    * provides a terminal user interface for detailed and exhaustive progress.
+    * provides a line renderer for log-like progress
+  * **lean-cli**
+    * Use `argh` to produce a usable binary with decent documentation that is smallest in size, usually 300kb less than `pretty-cli`.
+    * If `pretty-cli` is enabled as well, `small-cli` will take precedence, and you pay for building unnecessary dependencies.
+    * provides a line renderer for log-like progress
 * **prodash-line-renderer-crossterm** or **prodash-line-renderer-termion** _(mutually exclusive)_
   * The `--verbose` flag will be powered by an interactive progress mechanism that doubles as log as well as interactive progress
     that appears after a short duration.
   
-There are convenience features, which combine common choices of the above into one name
+There are **convenience features**, which combine common choices of the above into one name
 
-* **max** = *pretty-cli* + *fast*
-* **lean** = *lean-cli* + *fast*
+* **max** = *pretty-cli* + *fast* + *prodash/tui-renderer-crossterm*
+* **max-termion** = *pretty-cli* + *fast* + *prodash/tui-renderer-termion*
+* **lean** = *lean-cli* + *fast* + *prodash-line-renderer-crossterm*
+* **lean-termion** = *lean-cli* + *fast* + *prodash-line-renderer-termion*
+* **light** = *lean-cli* + *fast*
 * **small** = *lean-cli*
     
 ### git-features
@@ -237,6 +244,30 @@ All feature toggles are additive.
    * ...even if that includes only the most common usecases.
  * **Prefer to increment major version rapidly...**
    * ...instead of keeping major version zero for longer than needed.
+   
+## Plumbing vs Porcelain
+
+Both terms are coming from the `git` implementation itself, even though it won't necessarily point out which commands are plumbing and which
+are porcelain.
+The term *plumbing* refers to lower-level, more rarely used commands that complement porcelain by being invoked by it or for special use
+cases.
+The term *porcelain* refers to those with a decent user experience, they are primarily intended for use by humans.
+
+In any case, both types of programs must self-document their capabilities using through the `--help` flag.
+
+From there, we can derive a few rules to try to adhere to:
+
+### Plumbing
+
+* does not show any progress or logging output by default
+* if supported and logging is enabled, it will show timestamps in UTC
+
+### Porcelain
+
+* Provides output to stderr by default to provide progress information. There is no need to allow disabling it, but it shouldn't show up unless
+  the operation takes some time.
+* If timestamps are shown, they are in localtime.
+* Non-progress information goes to stdout.
 
 ## Maintenance Guide
 
@@ -263,6 +294,9 @@ Thus one has to post-process the file by reducing its size by one using `truncat
 
 ## Shortcomings
 
+* **lean** and **light** and **small** builds don't support non-UTF-8 paths
+  * This is because they depend on `argh`, which [does not yet support parsing OsStrings](https://github.com/google/argh/issues/33). We however
+    believe it eventually will do so and thus don't move on to [`pico-args`](https://github.com/RazrFalcon/pico-args/blob/master/examples/app.rs).
 * **Packfiles use memory maps**
   * Even though they are comfortable to use and fast, they squelch IO errors.
   * _potential remedy_: We could generalize the Pack to make it possible to work on in-memory buffers directly. That way, one
@@ -284,5 +318,5 @@ Thus one has to post-process the file by reducing its size by one using `truncat
 ## Fun facts
 
 * Originally I was really fascinated by [this problem](https://github.com/gitpython-developers/GitPython/issues/765#issuecomment-396072153)
-  and believe that with `gitoxide` it will be possible to provide the fastest implementation for that problem.
+  and believe that with `gitoxide` it will be possible to provide the fastest solution for it.
 
diff --git a/git-features/Cargo.toml b/git-features/Cargo.toml
@@ -31,7 +31,7 @@ fastsha1 = { package = "sha-1", version = "0.9.1", optional = true }
 
 # progress
 log = { version = "0.4.8", optional = true }
-prodash = { version = "7.0.0", optional = true, default-features = false }
+prodash = { version = "7.0.2", optional = true, default-features = false }
 
 [package.metadata.docs.rs]
 all-features = true
diff --git a/git-odb/src/pack/index/verify.rs b/git-odb/src/pack/index/verify.rs
@@ -127,7 +127,7 @@ impl index::File {
                         expected: self.checksum_of_pack(),
                     });
                 }
-                let mut progress = root.add_child(format!("Sha1 of pack at '{}'", pack.path().display()));
+                let mut progress = root.add_child(format!("Sha1 of pack"));
                 let (pack_res, id) = parallel::join(
                     move || {
                         let throughput = TimeThroughput::new(pack.data_len());
@@ -206,7 +206,7 @@ impl index::File {
                         let elapsed_s = Instant::now().duration_since(self.then).as_secs_f32();
                         let objects_per_second = (self.entries_seen as f32 / elapsed_s) as u32;
                         self.progress.lock().unwrap().info(format!(
-                            "Reduced {} objects in {:.2}s ({} objects/s, ~{}/s)",
+                            "Verified {} objects in {:.2}s ({} objects/s, ~{}/s)",
                             self.entries_seen,
                             elapsed_s,
                             objects_per_second,
@@ -221,7 +221,7 @@ impl index::File {
                 let input_chunks = index_entries
                     .chunks(CHUNK_SIZE.max(index_entries.len() / CHUNK_SIZE))
                     .into_iter();
-                let reduce_progress = std::sync::Mutex::new(root.add_child("reduce"));
+                let reduce_progress = std::sync::Mutex::new(root.add_child("Checking"));
                 reduce_progress
                     .lock()
                     .unwrap()
diff --git a/src/plumbing/lean.rs b/src/plumbing/lean.rs
@@ -39,7 +39,10 @@ mod options {
 use anyhow::Result;
 use git_features::progress;
 use gitoxide_core as core;
-use std::io::{stderr, stdout};
+use std::{
+    io::{stderr, stdout},
+    time::Duration,
+};
 
 #[cfg(not(any(
     feature = "prodash-line-renderer-crossterm",
@@ -59,11 +62,17 @@ fn prepare(verbose: bool, name: &str) -> (prodash::line::JoinHandle, progress::D
 
     let progress = prodash::Tree::new();
     let sub_progress = progress.add_child(name);
+    let output_is_terminal = atty::is(atty::Stream::Stderr);
     let handle = prodash::line::render(
         stderr(),
         progress,
         prodash::line::Options {
             level_filter: Some(std::ops::RangeInclusive::new(2, 2)),
+            frames_per_second: 6.0,
+            initial_delay: Some(Duration::from_millis(1000)),
+            output_is_terminal,
+            colored: output_is_terminal && crosstermion::color::allowed(),
+            timestamp: true,
             ..prodash::line::Options::default()
         },
     );
