feat(init): set man.viewer to be able to access git-branchless man-pages

Author: arxanas

src/commands/init.rs

@@ -308,13 +308,42 @@ the branchless workflow will work properly.
 }
 
 #[instrument]
-fn install_man_pages(effects: &Effects, repo: &Repo) -> eyre::Result<()> {
+fn install_man_pages(effects: &Effects, repo: &Repo, config: &mut Config) -> eyre::Result<()> {
     let should_install = cfg!(feature = "man-pages");
     if !should_install {
         return Ok(());
     }
 
-    let man_dir = repo.get_man1_dir();
+    let man_dir = repo.get_man_dir();
+    let man_dir_relative = {
+        let man_dir_relative = man_dir.strip_prefix(repo.get_path()).wrap_err_with(|| {
+            format!(
+                "Getting relative path for {:?} with respect to {:?}",
+                &man_dir,
+                repo.get_path()
+            )
+        })?;
+        &man_dir_relative.to_str().ok_or_else(|| {
+            eyre::eyre!(
+                "Could not convert man dir to UTF-8 string: {:?}",
+                &man_dir_relative
+            )
+        })?
+    };
+    config.set(
+        "man.branchless.cmd",
+        format!(
+            // FIXME: the path to the man directory is not shell-escaped.
+            //
+            // NB: the trailing `:` at the end of `MANPATH` indicates to `man`
+            // that it should try its normal lookup paths if the requested
+            // `man`-page cannot be found in the provided `MANPATH`.
+            "env MANPATH=.git/{}: man",
+            man_dir_relative
+        ),
+    )?;
+    config.set("man.viewer", "branchless")?;
+
     write_man_pages(&man_dir).wrap_err_with(|| format!("Writing man-pages to: {:?}", &man_dir))?;
     Ok(())
 }
@@ -459,7 +488,7 @@ pub fn init(effects: &Effects, git_run_info: &GitRunInfo) -> eyre::Result<()> {
     set_configs(&mut in_, effects, &repo, &mut config)?;
     install_hooks(effects, &repo)?;
     install_aliases(effects, &mut repo, &mut config, git_run_info)?;
-    install_man_pages(effects, &repo)?;
+    install_man_pages(effects, &repo, &mut config)?;
     writeln!(
         effects.get_output_stream(),
         "{}",

src/git/repo.rs

@@ -223,11 +223,12 @@ impl Repo {
         self.get_path().join("branchless").join("dag")
     }
 
-    /// Get the directory to store man-pages. Note that this is the `man/man1`
-    /// directory, specifically referring to the section 1 manual pages.
+    /// Get the directory to store man-pages. Note that this is the `man`
+    /// directory, and not a subsection thereof. `git-branchless` man-pages must
+    /// go into the `man/man1` directory to be found by `man`.
     #[instrument]
-    pub fn get_man1_dir(&self) -> PathBuf {
-        self.get_path().join("branchless").join("man").join("man1")
+    pub fn get_man_dir(&self) -> PathBuf {
+        self.get_path().join("branchless").join("man")
     }
 
     /// Get the connection to the SQLite database for this repository.

src/opts.rs

@@ -238,22 +238,23 @@ pub struct Opts {
 
 /// Generate and write man-pages into the specified directory.
 ///
-/// The generated files are named things like `git-branchless-smartlog.1`, so
-/// this directory should be of the form `path/to/man/man1`, to ensure that
-/// these files get generated into the correct man-page section.
+/// The generated files are named things like `man1/git-branchless-smartlog.1`,
+/// so this directory should be of the form `path/to/man`, to ensure that these
+/// files get generated into the correct man-page section.
 pub fn write_man_pages(man_dir: &Path) -> std::io::Result<()> {
-    std::fs::create_dir_all(&man_dir)?;
+    let man1_dir = man_dir.join("man1");
+    std::fs::create_dir_all(&man1_dir)?;
 
     let app = Opts::into_app();
-    generate_man_page(man_dir, "git-branchless", &app)?;
+    generate_man_page(&man1_dir, "git-branchless", &app)?;
     for subcommand in app.get_subcommands() {
         let subcommand_exe_name = format!("git-branchless-{}", subcommand.get_name());
-        generate_man_page(man_dir, &subcommand_exe_name, subcommand)?;
+        generate_man_page(&man1_dir, &subcommand_exe_name, subcommand)?;
     }
     Ok(())
 }
 
-fn generate_man_page(man_dir: &Path, name: &str, command: &App) -> std::io::Result<()> {
+fn generate_man_page(man1_dir: &Path, name: &str, command: &App) -> std::io::Result<()> {
     let mut manual = Manual::new(name);
     if let Some(about) = command.get_about() {
         manual = manual.about(about);
@@ -312,7 +313,7 @@ fn generate_man_page(man_dir: &Path, name: &str, command: &App) -> std::io::Resu
 
     // @nocommit do rest of man page info
 
-    let output_path = man_dir.join(format!("{}.1", name));
+    let output_path = man1_dir.join(format!("{}.1", name));
     std::fs::write(output_path, manual.render())?;
     Ok(())
 }

tests/command/test_init.rs

@@ -254,3 +254,73 @@ fn test_init_uninstall() -> eyre::Result<()> {
 
     Ok(())
 }
+
+#[cfg(feature = "man-pages")]
+#[test]
+fn test_man_viewer_installed() -> eyre::Result<()> {
+    use std::collections::HashMap;
+
+    use itertools::Itertools;
+
+    // The `man` executable isn't installed for most Windows Git installations.
+    // In particular, it's not installed on Github Actions.  It might be
+    // possible to install it manually, but I didn't bother.
+    //
+    // See https://stackoverflow.com/q/5517564,
+    // https://github.com/swcarpentry/shell-novice/issues/249
+    let should_skip = cfg!(windows);
+    if should_skip {
+        return Ok(());
+    }
+
+    let git = make_git()?;
+    git.init_repo()?;
+
+    // `env` and `man` are not on the sanitized testing `PATH`, so use the
+    // caller's `PATH` instead.
+    let testing_path = git.get_path_for_env();
+    let testing_path = std::env::split_paths(&testing_path).collect_vec();
+    let inherited_path = std::env::var_os("PATH").unwrap();
+    let inherited_path = std::env::split_paths(&inherited_path).collect_vec();
+    let env = {
+        let mut env = HashMap::new();
+        let full_path = std::env::join_paths(testing_path.iter().chain(inherited_path.iter()))?;
+        let full_path = full_path.to_str().unwrap().to_owned();
+        env.insert("PATH".to_string(), full_path);
+        env
+    };
+
+    {
+        let (stdout, _stderr) = git.run_with_options(
+            &["smartlog", "--help"],
+            &GitRunOptions {
+                env: env.clone(),
+                ..Default::default()
+            },
+        )?;
+        let first_word = stdout.split_whitespace().next();
+        insta::assert_debug_snapshot!(first_word, @r###"
+        Some(
+            "GIT-BRANCHLESS-SMARTLOG(1)",
+        )
+        "###);
+    }
+
+    {
+        let (stdout, _stderr) = git.run_with_options(
+            &["init", "--help"],
+            &GitRunOptions {
+                env,
+                ..Default::default()
+            },
+        )?;
+        let first_word = stdout.split_whitespace().next();
+        insta::assert_debug_snapshot!(first_word, @r###"
+        Some(
+            "GIT-INIT(1)",
+        )
+        "###);
+    }
+
+    Ok(())
+}