Skip to content

Commit 1dea8ec

Browse files
KSXGitHubclaudeCopilot
authored
feat: man page (#378)
Adds support for generating and distributing Unix man pages for the `pdu` command. The man page is automatically generated from the CLI argument definitions using a `clap`'s introspection APIs. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com> Co-authored-by: KSXGitHub <11488886+KSXGitHub@users.noreply.github.com>
1 parent f032de5 commit 1dea8ec

11 files changed

Lines changed: 581 additions & 1 deletion

File tree

‎.github/workflows/deploy.yaml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -271,6 +271,16 @@ jobs:
271271
asset_name: completion.elv
272272
asset_content_type: text/plain
273273

274+
- name: Upload Man Page
275+
uses: actions/upload-release-asset@v1.0.2
276+
env:
277+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
278+
with:
279+
upload_url: ${{ needs.create_release.outputs.upload_url }}
280+
asset_path: ./exports/pdu.1
281+
asset_name: pdu.1
282+
asset_content_type: text/plain
283+
274284
upload_release_assets:
275285
name: Upload Release Assets
276286

‎Cargo.toml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,11 @@ name = "pdu-completions"
4444
path = "cli/completions.rs"
4545
required-features = ["cli-completions"]
4646

47+
[[bin]]
48+
name = "pdu-man-page"
49+
path = "cli/man_page.rs"
50+
required-features = ["cli"]
51+
4752
[[bin]]
4853
name = "pdu-usage-md"
4954
path = "cli/usage_md.rs"

‎ci/github-actions/generate-pkgbuild.py3‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,8 @@ with open('./pkgbuild/parallel-disk-usage-bin/PKGBUILD', 'w') as pkgbuild:
5050
f'completion.{release_tag}.{ext}::{source_url_prefix}/completion.{ext}'
5151
for ext in supported_completions
5252
)
53-
content += f'source=(pdu-{checksum}::{source_url} {completion_source} {readme_url} {license_url})\n'
53+
man_page_source = f'pdu.{release_tag}.1::{source_url_prefix}/pdu.1'
54+
content += f'source=(pdu-{checksum}::{source_url} {completion_source} {man_page_source} {readme_url} {license_url})\n'
5455
content += f'_checksum={checksum}\n'
5556
completion_checksums = ' '.join('SKIP' for _ in supported_completions)
5657
content += f'_completion_checksums=({completion_checksums})\n'

‎cli/man_page.rs‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
use parallel_disk_usage::man_page::render_man_page;
2+
3+
fn main() {
4+
print!("{}", render_man_page());
5+
}

‎exports/pdu.1‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
.TH pdu 1 "pdu 0.21.1"
2+
.SH NAME
3+
pdu \- Summarize disk usage of the set of files, recursively for directories.
4+
.SH SYNOPSIS
5+
\fBpdu\fR [\fB\-\-json\-input\fR] [\fB\-\-json\-output\fR] [\fB\-b\fR|\fB\-\-bytes\-format\fR \fIBYTES_FORMAT\fR] [\fB\-H\fR|\fB\-\-deduplicate\-hardlinks\fR] [\fB\-x\fR|\fB\-\-one\-file\-system\fR] [\fB\-\-top\-down\fR] [\fB\-\-align\-right\fR] [\fB\-q\fR|\fB\-\-quantity\fR \fIQUANTITY\fR] [\fB\-d\fR|\fB\-\-max\-depth\fR \fIMAX_DEPTH\fR] [\fB\-w\fR|\fB\-\-total\-width\fR \fITOTAL_WIDTH\fR] [\fB\-\-column\-width\fR \fITREE_WIDTH\fR \fIBAR_WIDTH\fR] [\fB\-m\fR|\fB\-\-min\-ratio\fR \fIMIN_RATIO\fR] [\fB\-\-no\-sort\fR] [\fB\-s\fR|\fB\-\-silent\-errors\fR] [\fB\-p\fR|\fB\-\-progress\fR] [\fB\-\-threads\fR \fITHREADS\fR] [\fB\-\-omit\-json\-shared\-details\fR] [\fB\-\-omit\-json\-shared\-summary\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fIFILES\fR]...
6+
.SH DESCRIPTION
7+
Summarize disk usage of the set of files, recursively for directories.
8+
.PP
9+
Copyright: Apache\-2.0 © 2021 Hoàng Văn Khải <https://github.com/KSXGitHub/>
10+
.br
11+
Sponsor: https://github.com/sponsors/KSXGitHub
12+
.SH OPTIONS
13+
.TP
14+
[\fIFILES\fR]...
15+
List of files and/or directories
16+
.TP
17+
\fB\-\-json\-input\fR
18+
Read JSON data from stdin
19+
.RS
20+
.PP
21+
Cannot be used with \fB\-\-deduplicate\-hardlinks\fR, \fB\-\-one\-file\-system\fR, \fB\-\-quantity\fR.
22+
.RE
23+
.TP
24+
\fB\-\-json\-output\fR
25+
Print JSON data instead of an ASCII chart
26+
.TP
27+
\fB\-b\fR, \fB\-\-bytes\-format\fR \fI<BYTES_FORMAT>\fR [default: metric]
28+
How to display the numbers of bytes
29+
.RS
30+
.TP
31+
\fB\-\-bytes\-format plain\fR
32+
Display plain number of bytes without units
33+
.TP
34+
\fB\-\-bytes\-format metric\fR
35+
Use metric scale, i.e. 1K = 1000B, 1M = 1000K, and so on
36+
.TP
37+
\fB\-\-bytes\-format binary\fR
38+
Use binary scale, i.e. 1K = 1024B, 1M = 1024K, and so on
39+
.RE
40+
.TP
41+
\fB\-H\fR, \fB\-\-deduplicate\-hardlinks\fR, \fB\-\-detect\-links\fR, \fB\-\-dedupe\-links\fR
42+
Detect and subtract the sizes of hardlinks from their parent directory totals
43+
.RS
44+
.PP
45+
Cannot be used with \fB\-\-json\-input\fR.
46+
.RE
47+
.TP
48+
\fB\-x\fR, \fB\-\-one\-file\-system\fR
49+
Skip directories on different filesystems
50+
.RS
51+
.PP
52+
Cannot be used with \fB\-\-json\-input\fR.
53+
.RE
54+
.TP
55+
\fB\-\-top\-down\fR
56+
Print the tree top\-down instead of bottom\-up
57+
.TP
58+
\fB\-\-align\-right\fR
59+
Set the root of the bars to the right
60+
.TP
61+
\fB\-q\fR, \fB\-\-quantity\fR \fI<QUANTITY>\fR [default: block\-size]
62+
Aspect of the files/directories to be measured
63+
.RS
64+
.TP
65+
\fB\-\-quantity apparent\-size\fR
66+
Measure apparent sizes
67+
.TP
68+
\fB\-\-quantity block\-size\fR
69+
Measure block sizes (block\-count * 512B)
70+
.TP
71+
\fB\-\-quantity block\-count\fR
72+
Count numbers of blocks
73+
.RE
74+
.RS
75+
.PP
76+
Cannot be used with \fB\-\-json\-input\fR.
77+
.RE
78+
.TP
79+
\fB\-d\fR, \fB\-\-max\-depth\fR, \fB\-\-depth\fR \fI<MAX_DEPTH>\fR [default: 10]
80+
Maximum depth to display the data. Could be either "inf" or a positive integer
81+
.TP
82+
\fB\-w\fR, \fB\-\-total\-width\fR, \fB\-\-width\fR \fI<TOTAL_WIDTH>\fR
83+
Width of the visualization
84+
.RS
85+
.PP
86+
Cannot be used with \fB\-\-column\-width\fR.
87+
.RE
88+
.TP
89+
\fB\-\-column\-width\fR \fI<TREE_WIDTH>\fR \fI<BAR_WIDTH>\fR
90+
Maximum widths of the tree column and width of the bar column
91+
.RS
92+
.PP
93+
Cannot be used with \fB\-\-total\-width\fR.
94+
.RE
95+
.TP
96+
\fB\-m\fR, \fB\-\-min\-ratio\fR \fI<MIN_RATIO>\fR [default: 0.01]
97+
Minimal size proportion required to appear
98+
.TP
99+
\fB\-\-no\-sort\fR
100+
Do not sort the branches in the tree
101+
.TP
102+
\fB\-s\fR, \fB\-\-silent\-errors\fR, \fB\-\-no\-errors\fR
103+
Prevent filesystem error messages from appearing in stderr
104+
.TP
105+
\fB\-p\fR, \fB\-\-progress\fR
106+
Report progress being made at the expense of performance
107+
.TP
108+
\fB\-\-threads\fR \fI<THREADS>\fR [default: auto]
109+
Set the maximum number of threads to spawn. Could be either "auto", "max", or a positive integer
110+
.TP
111+
\fB\-\-omit\-json\-shared\-details\fR
112+
Do not output `.shared.details` in the JSON output
113+
.TP
114+
\fB\-\-omit\-json\-shared\-summary\fR
115+
Do not output `.shared.summary` in the JSON output
116+
.TP
117+
\fB\-h\fR, \fB\-\-help\fR
118+
Print help (see a summary with '\-h')
119+
.TP
120+
\fB\-V\fR, \fB\-\-version\fR
121+
Print version
122+
.SH EXAMPLES
123+
.TP
124+
Show disk usage chart of current working directory
125+
.nf
126+
\fB$ pdu\fR
127+
.fi
128+
.TP
129+
Show disk usage chart of a single file or directory
130+
.nf
131+
\fB$ pdu path/to/file/or/directory\fR
132+
.fi
133+
.TP
134+
Compare disk usages of multiple files and/or directories
135+
.nf
136+
\fB$ pdu file.txt dir/\fR
137+
.fi
138+
.TP
139+
Show chart in apparent sizes instead of block sizes
140+
.nf
141+
\fB$ pdu \-\-quantity=apparent\-size\fR
142+
.fi
143+
.TP
144+
Detect and subtract the sizes of hardlinks from their parent nodes
145+
.nf
146+
\fB$ pdu \-\-deduplicate\-hardlinks\fR
147+
.fi
148+
.TP
149+
Show sizes in plain numbers instead of metric units
150+
.nf
151+
\fB$ pdu \-\-bytes\-format=plain\fR
152+
.fi
153+
.TP
154+
Show sizes in base 2¹⁰ units (binary) instead of base 10³ units (metric)
155+
.nf
156+
\fB$ pdu \-\-bytes\-format=binary\fR
157+
.fi
158+
.TP
159+
Show disk usage chart of all entries regardless of size
160+
.nf
161+
\fB$ pdu \-\-min\-ratio=0\fR
162+
.fi
163+
.TP
164+
Only show disk usage chart of entries whose size is at least 5% of total
165+
.nf
166+
\fB$ pdu \-\-min\-ratio=0.05\fR
167+
.fi
168+
.TP
169+
Show disk usage data as JSON instead of chart
170+
.nf
171+
\fB$ pdu \-\-min\-ratio=0 \-\-max\-depth=inf \-\-json\-output | jq\fR
172+
.fi
173+
.TP
174+
Visualize existing JSON representation of disk usage data
175+
.nf
176+
\fB$ pdu \-\-json\-input < disk\-usage.json\fR
177+
.fi
178+
.SH VERSION
179+
v0.21.1

‎generate-completions.sh‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,4 @@ gen elvish completion.elv
1717
./run.sh pdu --help | sed 's/[[:space:]]*$//' > exports/long.help
1818
./run.sh pdu -h | sed 's/[[:space:]]*$//' > exports/short.help
1919
./run.sh pdu-usage-md > USAGE.md
20+
./run.sh pdu-man-page > exports/pdu.1

‎src/lib.rs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ pub mod app;
1515
#[cfg(feature = "cli")]
1616
pub mod args;
1717
#[cfg(feature = "cli")]
18+
pub mod man_page;
19+
#[cfg(feature = "cli")]
1820
pub mod runtime_error;
1921
#[cfg(feature = "cli")]
2022
pub mod usage_md;

0 commit comments

Comments
 (0)