Skip to content

Commit b83af13

Browse files
CopilotKSXGitHub
Copilot
and
KSXGitHub
committed
docs: add CLI usage documentation and sync_help tests
Co-authored-by: KSXGitHub <11488886+KSXGitHub@users.noreply.github.com>
1 parent 3b26ddd commit b83af13

5 files changed

Lines changed: 243 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,10 @@ The benchmark was generated by [a GitHub Workflow](https://github.com/KSXGitHub/
6464
* Do not differentiate filesystem: Mounted folders are counted as normal folders.
6565
* The runtime is optimized at the expense of binary size.
6666

67+
## Usage
68+
69+
See [exports/long.help](https://github.com/KSXGitHub/parallel-disk-usage/blob/master/exports/long.help) for the full help text.
70+
6771
## Development
6872

6973
### Prerequisites

‎exports/long.help‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
Summarize disk usage of the set of files, recursively for directories.
2+
3+
Copyright: Apache-2.0 © 2021 Hoàng Văn Khải <https://github.com/KSXGitHub/>
4+
Sponsor: https://github.com/sponsors/KSXGitHub
5+
6+
Usage: pdu [OPTIONS] [FILES]...
7+
8+
Arguments:
9+
[FILES]...
10+
List of files and/or directories
11+
12+
Options:
13+
--json-input
14+
Read JSON data from stdin
15+
16+
--json-output
17+
Print JSON data instead of an ASCII chart
18+
19+
-b, --bytes-format <BYTES_FORMAT>
20+
How to display the numbers of bytes
21+
22+
Possible values:
23+
- plain: Display plain number of bytes without units
24+
- metric: Use metric scale, i.e. 1K = 1000B, 1M = 1000K, and so on
25+
- binary: Use binary scale, i.e. 1K = 1024B, 1M = 1024K, and so on
26+
27+
[default: metric]
28+
29+
-H, --deduplicate-hardlinks
30+
Detect and subtract the sizes of hardlinks from their parent directory totals
31+
32+
[aliases: --detect-links, --dedupe-links]
33+
34+
--top-down
35+
Print the tree top-down instead of bottom-up
36+
37+
--align-right
38+
Set the root of the bars to the right
39+
40+
-q, --quantity <QUANTITY>
41+
Aspect of the files/directories to be measured
42+
43+
Possible values:
44+
- apparent-size: Measure apparent sizes
45+
- block-size: Measure block sizes (block-count * 512B)
46+
- block-count: Count numbers of blocks
47+
48+
[default: block-size]
49+
50+
-d, --max-depth <MAX_DEPTH>
51+
Maximum depth to display the data. Could be either "inf" or a positive integer
52+
53+
[default: 10]
54+
[aliases: --depth]
55+
56+
-w, --total-width <TOTAL_WIDTH>
57+
Width of the visualization
58+
59+
[aliases: --width]
60+
61+
--column-width <TREE_WIDTH> <BAR_WIDTH>
62+
Maximum widths of the tree column and width of the bar column
63+
64+
-m, --min-ratio <MIN_RATIO>
65+
Minimal size proportion required to appear
66+
67+
[default: 0.01]
68+
69+
--no-sort
70+
Do not sort the branches in the tree
71+
72+
-s, --silent-errors
73+
Prevent filesystem error messages from appearing in stderr
74+
75+
[aliases: --no-errors]
76+
77+
-p, --progress
78+
Report progress being made at the expense of performance
79+
80+
--threads <THREADS>
81+
Set the maximum number of threads to spawn. Could be either "auto", "max", or a positive integer
82+
83+
[default: auto]
84+
85+
--omit-json-shared-details
86+
Do not output `.shared.details` in the JSON output
87+
88+
--omit-json-shared-summary
89+
Do not output `.shared.summary` in the JSON output
90+
91+
-h, --help
92+
Print help (see a summary with '-h')
93+
94+
-V, --version
95+
Print version
96+
97+
Examples:
98+
Show disk usage chart of current working directory
99+
$ pdu
100+
101+
Show disk usage chart of a single file or directory
102+
$ pdu path/to/file/or/directory
103+
104+
Compare disk usages of multiple files and/or directories
105+
$ pdu file.txt dir/
106+
107+
Show chart in apparent sizes instead of block sizes
108+
$ pdu --quantity=apparent-size
109+
110+
Detect and subtract the sizes of hardlinks from their parent nodes
111+
$ pdu --deduplicate-hardlinks
112+
113+
Show sizes in plain numbers instead of metric units
114+
$ pdu --bytes-format=plain
115+
116+
Show sizes in base 2¹⁰ units (binary) instead of base 10³ units (metric)
117+
$ pdu --bytes-format=binary
118+
119+
Show disk usage chart of all entries regardless of size
120+
$ pdu --min-ratio=0
121+
122+
Only show disk usage chart of entries whose size is at least 5% of total
123+
$ pdu --min-ratio=0.05
124+
125+
Show disk usage data as JSON instead of chart
126+
$ pdu --min-ratio=0 --max-depth=inf --json-output | jq
127+
128+
Visualize existing JSON representation of disk usage data
129+
$ pdu --json-input < disk-usage.json

‎exports/short.help‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
Summarize disk usage of the set of files, recursively for directories.
2+
3+
Usage: pdu [OPTIONS] [FILES]...
4+
5+
Arguments:
6+
[FILES]... List of files and/or directories
7+
8+
Options:
9+
--json-input
10+
Read JSON data from stdin
11+
--json-output
12+
Print JSON data instead of an ASCII chart
13+
-b, --bytes-format <BYTES_FORMAT>
14+
How to display the numbers of bytes [default: metric] [possible values: plain, metric, binary]
15+
-H, --deduplicate-hardlinks
16+
Detect and subtract the sizes of hardlinks from their parent directory totals [aliases: --detect-links, --dedupe-links]
17+
--top-down
18+
Print the tree top-down instead of bottom-up
19+
--align-right
20+
Set the root of the bars to the right
21+
-q, --quantity <QUANTITY>
22+
Aspect of the files/directories to be measured [default: block-size] [possible values: apparent-size, block-size, block-count]
23+
-d, --max-depth <MAX_DEPTH>
24+
Maximum depth to display the data. Could be either "inf" or a positive integer [default: 10] [aliases: --depth]
25+
-w, --total-width <TOTAL_WIDTH>
26+
Width of the visualization [aliases: --width]
27+
--column-width <TREE_WIDTH> <BAR_WIDTH>
28+
Maximum widths of the tree column and width of the bar column
29+
-m, --min-ratio <MIN_RATIO>
30+
Minimal size proportion required to appear [default: 0.01]
31+
--no-sort
32+
Do not sort the branches in the tree
33+
-s, --silent-errors
34+
Prevent filesystem error messages from appearing in stderr [aliases: --no-errors]
35+
-p, --progress
36+
Report progress being made at the expense of performance
37+
--threads <THREADS>
38+
Set the maximum number of threads to spawn. Could be either "auto", "max", or a positive integer [default: auto]
39+
--omit-json-shared-details
40+
Do not output `.shared.details` in the JSON output
41+
--omit-json-shared-summary
42+
Do not output `.shared.summary` in the JSON output
43+
-h, --help
44+
Print help (see more with '--help')
45+
-V, --version
46+
Print version
47+
48+
Examples:
49+
$ pdu
50+
$ pdu path/to/file/or/directory
51+
$ pdu file.txt dir/
52+
$ pdu --quantity=apparent-size
53+
$ pdu --deduplicate-hardlinks
54+
$ pdu --bytes-format=plain
55+
$ pdu --bytes-format=binary
56+
$ pdu --min-ratio=0
57+
$ pdu --min-ratio=0.05
58+
$ pdu --min-ratio=0 --max-depth=inf --json-output | jq
59+
$ pdu --json-input < disk-usage.json

‎generate-completions.sh‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,6 @@ gen fish completion.fish
1313
gen zsh completion.zsh
1414
gen powershell completion.ps1
1515
gen elvish completion.elv
16+
17+
./run.sh pdu --help > exports/long.help
18+
./run.sh pdu -h > exports/short.help

‎tests/sync_help.rs‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
#![cfg(feature = "cli")]
2+
3+
pub mod _utils;
4+
pub use _utils::*;
5+
6+
use command_extra::CommandExtra;
7+
use pipe_trait::Pipe;
8+
use std::{
9+
fs,
10+
path::PathBuf,
11+
process::{Command, Stdio},
12+
};
13+
14+
fn exports_dir() -> PathBuf {
15+
PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("exports")
16+
}
17+
18+
fn pdu_help(long: bool) -> String {
19+
let flag = if long { "--help" } else { "-h" };
20+
Command::new(PDU)
21+
.with_arg(flag)
22+
.with_stdin(Stdio::null())
23+
.with_stdout(Stdio::piped())
24+
.with_stderr(Stdio::null())
25+
.output()
26+
.unwrap_or_else(|error| panic!("failed to spawn pdu {flag}: {error}"))
27+
.pipe(stdout_text)
28+
}
29+
30+
#[test]
31+
fn long_help_is_up_to_date() {
32+
let actual = pdu_help(true);
33+
let expected = fs::read_to_string(exports_dir().join("long.help"))
34+
.expect("read exports/long.help")
35+
.trim_end()
36+
.to_string();
37+
assert_eq!(actual, expected);
38+
}
39+
40+
#[test]
41+
fn short_help_is_up_to_date() {
42+
let actual = pdu_help(false);
43+
let expected = fs::read_to_string(exports_dir().join("short.help"))
44+
.expect("read exports/short.help")
45+
.trim_end()
46+
.to_string();
47+
assert_eq!(actual, expected);
48+
}

0 commit comments

Comments
 (0)