feat: add man page generation to all crates and fix CI/CD workflows

Add clap_mangen and --generate-man support to git-ledger and git-chain,
matching the existing pattern in git-metadata.

feat: add man page generation to git-ledger and git-chain
fix: broaden CD tag regex to match all three crate prefixes
fix: CI man job uses checkout@v4 and generates for all crates
chore: remove redundant CI caching (handled by setup-rust-toolchain)
Assisted-by: Zed (Claude Opus 4.6)

Author: jdc-pub

.github/workflows/CD.yml

@@ -21,7 +21,7 @@ jobs:
         if: github.event_name == 'release'
         run: |
           TAG="${{ github.event.release.tag_name }}"
-          if [[ "$TAG" =~ ^git-metadata-v[0-9]+\.[0-9]+\.[0-9]+(-.*)?$ ]]; then
+          if [[ "$TAG" =~ ^(git-metadata|git-ledger|git-chain)-v[0-9]+\.[0-9]+\.[0-9]+(-.*)?$ ]]; then
             echo "match=true" >> "$GITHUB_OUTPUT"
           else
             echo "match=false" >> "$GITHUB_OUTPUT"

.github/workflows/CI.yml

@@ -110,26 +110,11 @@ jobs:
       - uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
           cache: true
-      - name: Cache Cargo registry
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cargo/registry/index/
-            ~/.cargo/registry/cache/
-            ~/.cargo/git/db/
-          key: ${{ runner.os }}-cargo-registry-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-cargo-registry-
-      - name: Cache Cargo build
-        uses: actions/cache@v4
-        with:
-          path: target
-          key: ${{ runner.os }}-cargo-build-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-cargo-build-
       - name: Generate man pages
         run: |
           cargo run --package git-metadata -- --generate-man target/debug/man
+          cargo run --package git-ledger -- --generate-man target/debug/man
+          cargo run --package git-chain -- --generate-man target/debug/man
 
   ci:
     name: CI

Cargo.lock

@@ -16,6 +16,7 @@ path = "src/main.rs"
 
 [dependencies]
 clap = { version = "4.5.60", features = ["derive"] }
+clap_mangen = "0.2.31"
 git2 = "0.20.4"
 
 [dev-dependencies]

crates/git-chain/Cargo.toml

@@ -1,13 +1,21 @@
 mod cli;
 
-use clap::Parser;
+use clap::{CommandFactory, Parser};
 use cli::{Cli, Command};
 use git_chain::Chain;
 use git2::{Oid, Repository};
-use std::path::Path;
+use std::path::{Path, PathBuf};
 use std::process;
 
 fn main() {
+    if let Some(dir) = parse_generate_man_flag() {
+        if let Err(e) = generate_man_page(dir) {
+            eprintln!("Error: {}", e);
+            process::exit(1);
+        }
+        return;
+    }
+
     let cli = Cli::parse();
 
     if let Err(e) = run(&cli) {
@@ -90,3 +98,64 @@ fn run(cli: &Cli) -> Result<(), Box<dyn std::error::Error>> {
 
     Ok(())
 }
+
+/// Check for `--generate-man <DIR>` before clap parses, so it doesn't
+/// conflict with the required subcommand.
+fn parse_generate_man_flag() -> Option<PathBuf> {
+    let args: Vec<String> = std::env::args().collect();
+    let pos = args.iter().position(|a| a == "--generate-man")?;
+    let dir = args
+        .get(pos + 1)
+        .map(PathBuf::from)
+        .unwrap_or_else(default_man_dir);
+    Some(dir)
+}
+
+fn default_man_dir() -> PathBuf {
+    std::env::var_os("XDG_DATA_HOME")
+        .map(PathBuf::from)
+        .unwrap_or_else(|| {
+            let home = std::env::var_os("HOME").expect("HOME is not set");
+            PathBuf::from(home).join(".local/share")
+        })
+        .join("man")
+}
+
+fn generate_man_page(output_dir: PathBuf) -> Result<(), Box<dyn std::error::Error>> {
+    let man1_dir = output_dir.join("man1");
+    std::fs::create_dir_all(&man1_dir)?;
+
+    let cmd = Cli::command();
+    let man = clap_mangen::Man::new(cmd);
+    let mut buffer = Vec::new();
+    man.render(&mut buffer)?;
+
+    let man_path = man1_dir.join("git-chain.1");
+    std::fs::write(&man_path, buffer)?;
+
+    let output_dir = output_dir.canonicalize()?;
+    eprintln!("Wrote man page to {}", man_path.canonicalize()?.display());
+
+    if !manpath_covers(&output_dir) {
+        eprintln!();
+        eprintln!("You may need to add this to your shell environment:");
+        eprintln!();
+        eprintln!("  export MANPATH=\"{}:$MANPATH\"", output_dir.display());
+    }
+    Ok(())
+}
+
+fn manpath_covers(dir: &std::path::Path) -> bool {
+    let Some(manpath) = std::env::var_os("MANPATH") else {
+        return false;
+    };
+    for component in std::env::split_paths(&manpath) {
+        let Ok(component) = component.canonicalize() else {
+            continue;
+        };
+        if dir.starts_with(&component) {
+            return true;
+        }
+    }
+    false
+}

crates/git-chain/src/main.rs

@@ -16,6 +16,7 @@ path = "src/main.rs"
 
 [dependencies]
 clap = { version = "4.5.60", features = ["derive"] }
+clap_mangen = "0.2.31"
 git2 = "0.20.4"
 
 [dev-dependencies]

crates/git-ledger/Cargo.toml

@@ -1,14 +1,22 @@
 mod cli;
 
-use clap::Parser;
+use clap::{CommandFactory, Parser};
 use cli::{Cli, Command};
 use git_ledger::{IdStrategy, Ledger, Mutation};
 use git2::Repository;
 use std::io::Read;
-use std::path::Path;
+use std::path::{Path, PathBuf};
 use std::process;
 
 fn main() {
+    if let Some(dir) = parse_generate_man_flag() {
+        if let Err(e) = generate_man_page(dir) {
+            eprintln!("Error: {}", e);
+            process::exit(1);
+        }
+        return;
+    }
+
     let cli = Cli::parse();
 
     if let Err(e) = run(&cli) {
@@ -148,3 +156,66 @@ fn run(cli: &Cli) -> Result<(), Box<dyn std::error::Error>> {
 
     Ok(())
 }
+
+/// Check for `--generate-man <DIR>` before clap parses, so it doesn't
+/// conflict with the required subcommand.
+fn parse_generate_man_flag() -> Option<PathBuf> {
+    let args: Vec<String> = std::env::args().collect();
+    let pos = args.iter().position(|a| a == "--generate-man")?;
+    let dir = args
+        .get(pos + 1)
+        .map(PathBuf::from)
+        .unwrap_or_else(default_man_dir);
+    Some(dir)
+}
+
+fn default_man_dir() -> PathBuf {
+    std::env::var_os("XDG_DATA_HOME")
+        .map(PathBuf::from)
+        .unwrap_or_else(|| {
+            let home = std::env::var_os("HOME").expect("HOME is not set");
+            PathBuf::from(home).join(".local/share")
+        })
+        .join("man")
+}
+
+fn generate_man_page(output_dir: PathBuf) -> Result<(), Box<dyn std::error::Error>> {
+    let man1_dir = output_dir.join("man1");
+    std::fs::create_dir_all(&man1_dir)?;
+
+    let cmd = Cli::command();
+    let man = clap_mangen::Man::new(cmd);
+    let mut buffer = Vec::new();
+    man.render(&mut buffer)?;
+
+    let man_path = man1_dir.join("git-ledger.1");
+    std::fs::write(&man_path, buffer)?;
+
+    let output_dir = output_dir.canonicalize()?;
+    eprintln!("Wrote man page to {}", man_path.canonicalize()?.display());
+
+    if !manpath_covers(&output_dir) {
+        eprintln!();
+        eprintln!("You may need to add this to your shell environment:");
+        eprintln!();
+        eprintln!("  export MANPATH=\"{}:$MANPATH\"", output_dir.display());
+    }
+    Ok(())
+}
+
+/// Returns `true` if `dir` is equal to, or a subdirectory of, any component
+/// in the `MANPATH` environment variable.
+fn manpath_covers(dir: &std::path::Path) -> bool {
+    let Some(manpath) = std::env::var_os("MANPATH") else {
+        return false;
+    };
+    for component in std::env::split_paths(&manpath) {
+        let Ok(component) = component.canonicalize() else {
+            continue;
+        };
+        if dir.starts_with(&component) {
+            return true;
+        }
+    }
+    false
+}