feat(init): create install-man-pages subcommand

git-branchless-init/src/lib.rs

@@ -22,7 +22,7 @@ use lib::util::ExitCode;
 use path_slash::PathExt;
 use tracing::{instrument, warn};
 
-use git_branchless_opts::{write_man_pages, InitArgs};
+use git_branchless_opts::{write_man_pages, InitArgs, InstallManPagesArgs};
 use lib::core::config::{get_default_branch_name, get_default_hooks_dir, get_hooks_dir};
 use lib::core::dag::Dag;
 use lib::core::effects::Effects;
@@ -684,6 +684,17 @@ pub fn command_main(ctx: CommandContext, args: InitArgs) -> eyre::Result<ExitCod
     }
 }
 
+/// Install the man-pages for `git-branchless` to the provided path.
+#[instrument]
+pub fn command_install_man_pages(
+    ctx: CommandContext,
+    args: InstallManPagesArgs,
+) -> eyre::Result<ExitCode> {
+    let InstallManPagesArgs { path } = args;
+    write_man_pages(&path)?;
+    Ok(ExitCode(0))
+}
+
 #[cfg(test)]
 mod tests {
     use super::{update_between_lines, ALL_ALIASES, UPDATE_MARKER_END, UPDATE_MARKER_START};

git-branchless-opts/src/lib.rs

@@ -265,6 +265,14 @@ pub struct InitArgs {
     pub main_branch_name: Option<String>,
 }
 
+/// Install git-branchless's man-pages to the given path.
+#[derive(Debug, Parser)]
+pub struct InstallManPagesArgs {
+    /// The path to install to. An example path might be `/usr/share/man`. The
+    /// provded path will be appended with `man1`, etc., as appropriate.
+    pub path: PathBuf,
+}
+
 /// Query the commit graph using the "revset" language and print matching
 /// commits.
 ///
@@ -425,6 +433,9 @@ pub enum Command {
     /// Initialize the branchless workflow for this repository.
     Init(InitArgs),
 
+    /// Install git-branchless's man-pages to the given path.
+    InstallManPages(InstallManPagesArgs),
+
     /// Move a subtree of commits from one location to another.
     ///
     /// By default, `git move` tries to move the entire current stack if you
@@ -889,7 +900,11 @@ pub fn write_man_pages(man_dir: &Path) -> std::io::Result<()> {
     let man1_dir = man_dir.join("man1");
     std::fs::create_dir_all(&man1_dir)?;
 
-    let app = Opts::command();
+    let app =
+        // Explicitly set the name here, or else clap thinks that the name of the
+        // command is `git-branchless-opts` (and that its subcommands are
+        // `git-branchless-opts-amend`, etc.).
+        Opts::command().name("git-branchless");
     generate_man_page(&man1_dir, "git-branchless", &app)?;
     for subcommand in app.get_subcommands() {
         let subcommand_exe_name = format!("git-branchless-{}", subcommand.get_name());
@@ -901,7 +916,14 @@ pub fn write_man_pages(man_dir: &Path) -> std::io::Result<()> {
 fn generate_man_page(man1_dir: &Path, name: &str, command: &ClapCommand) -> std::io::Result<()> {
     let rendered_man_page = {
         let mut buffer = Vec::new();
-        clap_mangen::Man::new(command.clone()).render(&mut buffer)?;
+        clap_mangen::Man::new(command.clone())
+            // The rendered man-page command name would be the subcommand only
+            // (such as `amend(1)` instead of `git-branchless-amend(1)`), so
+            // override the name here. Also, the top-level man-page name will be
+            // `git-branchless-opts(1)` instead of `git-branchless(1)`, which is
+            // also handled by this call to `.title`.
+            .title(name)
+            .render(&mut buffer)?;
         buffer
     };
     let output_path = man1_dir.join(format!("{name}.1"));

git-branchless/src/commands/mod.rs

@@ -70,6 +70,10 @@ fn command_main(ctx: CommandContext, opts: Opts) -> eyre::Result<ExitCode> {
 
         Command::Init(args) => git_branchless_init::command_main(ctx, args)?,
 
+        Command::InstallManPages(args) => {
+            git_branchless_init::command_install_man_pages(ctx, args)?
+        }
+
         Command::Move {
             source,
             dest,

git-branchless/tests/test_init.rs

@@ -633,3 +633,131 @@ fn test_init_worktree() -> eyre::Result<()> {
 
     Ok(())
 }
+
+#[test]
+fn test_install_man_pages() -> eyre::Result<()> {
+    let git = make_git()?;
+    git.init_repo()?;
+    let dir = "foo";
+    git.branchless("install-man-pages", &[dir])?;
+    let man_page_contents = std::fs::read(
+        git.repo_path
+            .join(dir)
+            .join("man1")
+            .join("git-branchless.1"),
+    )?;
+    let man_page_contents = String::from_utf8_lossy(&man_page_contents);
+    insta::assert_snapshot!(man_page_contents, @r###"
+    .ie \n(.g .ds Aq \(aq
+    .el .ds Aq '
+    .TH git-branchless 1  "git-branchless 0.7.0" 
+    .SH NAME
+    git\-branchless \- Branchless workflow for Git
+    .SH SYNOPSIS
+    \fBgit\-branchless\fR [\fB\-C \fR] [\fB\-\-color\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fIsubcommands\fR>
+    .SH DESCRIPTION
+    Branchless workflow for Git.
+    .PP
+    See the documentation at <https://github.com/arxanas/git\-branchless/wiki>.
+    .SH OPTIONS
+    .TP
+    \fB\-C\fR=\fIWORKING_DIRECTORY\fR
+    Change to the given directory before executing the rest of the program. (The option is called `\-C` for symmetry with Git.)
+    .TP
+    \fB\-\-color\fR=\fICOLOR\fR
+    Flag to force enable or disable terminal colors
+    .br
+
+    .br
+    \fIPossible values:\fR
+    .RS 14
+    .IP \(bu 2
+    auto: Automatically determine whether to display colors from the terminal and environment variables. This is the default behavior
+    .IP \(bu 2
+    always: Always display terminal colors
+    .IP \(bu 2
+    never: Never display terminal colors
+    .RE
+    .TP
+    \fB\-h\fR, \fB\-\-help\fR
+    Print help information (use `\-h` for a summary)
+    .TP
+    \fB\-V\fR, \fB\-\-version\fR
+    Print version information
+    .SH SUBCOMMANDS
+    .TP
+    git\-branchless\-amend(1)
+    Amend the current HEAD commit
+    .TP
+    git\-branchless\-bug\-report(1)
+    Gather information about recent operations to upload as part of a bug report
+    .TP
+    git\-branchless\-gc(1)
+    Run internal garbage collection
+    .TP
+    git\-branchless\-hide(1)
+    Hide the provided commits from the smartlog
+    .TP
+    git\-branchless\-init(1)
+    Initialize the branchless workflow for this repository
+    .TP
+    git\-branchless\-install\-man\-pages(1)
+    Install git\-branchless\*(Aqs man\-pages to the given path
+    .TP
+    git\-branchless\-move(1)
+    Move a subtree of commits from one location to another
+    .TP
+    git\-branchless\-next(1)
+    Move to a later commit in the current stack
+    .TP
+    git\-branchless\-prev(1)
+    Move to an earlier commit in the current stack
+    .TP
+    git\-branchless\-query(1)
+    Query the commit graph using the "revset" language and print matching commits
+    .TP
+    git\-branchless\-repair(1)
+    Restore internal invariants by reconciling the internal operation log with the state of the Git repository
+    .TP
+    git\-branchless\-restack(1)
+    Fix up commits abandoned by a previous rewrite operation
+    .TP
+    git\-branchless\-record(1)
+    Create a commit by interactively selecting which changes to include
+    .TP
+    git\-branchless\-reword(1)
+    Reword commits
+    .TP
+    git\-branchless\-smartlog(1)
+    `smartlog` command
+    .TP
+    git\-branchless\-submit(1)
+    Push commits to a remote
+    .TP
+    git\-branchless\-switch(1)
+    Switch to the provided branch or commit
+    .TP
+    git\-branchless\-sync(1)
+    Move any local commit stacks on top of the main branch
+    .TP
+    git\-branchless\-test(1)
+    Run a command on each commit in a given set and aggregate the results
+    .TP
+    git\-branchless\-undo(1)
+    Browse or return to a previous state of the repository
+    .TP
+    git\-branchless\-unhide(1)
+    Unhide previously\-hidden commits from the smartlog
+    .TP
+    git\-branchless\-wrap(1)
+    Wrap a Git command inside a branchless transaction
+    .TP
+    git\-branchless\-help(1)
+    Print this message or the help of the given subcommand(s)
+    .SH VERSION
+    v0.7.0
+    .SH AUTHORS
+    Waleed Khan <me@waleedkhan.name>
+    "###);
+    Ok(())
+}