Support man-pages

[arxanas]

As per the issue at #88 (comment), some invocations, such as git move --help, fail to show anything useful.

There are several possible approaches to fix this:

• Install man-pages upon installation of the package.
  • But this appears to be impossible with Cargo at present. It requires support from the system package manager.
• Install man-pages upon git branchless init.
  • This might be somewhat strange for NixOS, which probably doesn't want programs to install files which change their behavior materially.
• Install temporary man-pages somewhere, and set MANPATH when running under git-branchless wrap.

[arxanas]

Investigation so far:

First of all, there's no solution currently to have Cargo install man-pages. It requires support from the system package manager. I did find that it was possible to use clap for argument-parsing and introspect all of the arguments at runtime, and then use man to write man-pages to disk, during the build process. These artifacts are written to the OUT_DIR environment variable directory, and the system package manager would have to move them into place from there.

It should be possible to create a set of man-pages upon running git branchless init. The question is where to store them. I'd rather not try to store them globally:

• It seems rude to write to random locations on disk.
• It might not work to do so under NixOS or other operating systems.
• It's not clear where to store them, although a reasonable place would be alongside the git-branchless executable.
• It would be hard or risky to delete them afterwards (especially considering that git branchless init --uninstall doesn't mean that you should get rid of the man-pages unless all repositories have uninstalled git-branchless).

A more sensible solution would be to store the man-pages under .git/branchless, and then adjust the MANPATH variable at runtime when invoking man to use that path. Then we can also cleanly remove the man-pages upon uninstallation.

The next issue is that git --help works in an unfortunate way. It operates by rewriting the command-line argument, and then invoking git help. git help is capable of looking up man-pages, but only with regular aliases (aliases of the form foo bar, which would invoke git foo bar), not shell aliases (those aliases which start with ! and run an arbitrary command). That implies that if we want to provide man-pages for e.g. git-branchless smartlog, we really need to have an executable called git-branchless-smartlog on PATH.

I looked into whether it's possible to store a set of symlinks or scripts under .git/branchless and have the aliases invoke them. It appears impossible to me to customize what PATH is searched when invoking a user-defined Git subcommand by using Git configuration directives. It would be possible to set environment variables using git-branchless wrap, but I don't want to make it a requirement to have to wrap your commands in git-branchless wrap, so that it's not necessary to create a shell alias in order to start using git-branchless.

So it seems like we really need to install executables called git-branchless-smartlog, etc., alongside the git-branchless executable. One way, again, is to install them upon the first git branchless init, but it has the same issues as installing man-pages above. Another is to request support from the system package manager.

A working solution is to actually just create extra executables in Cargo.toml, one for each subcommand. I changed things so that they can all use the same entry point, and they look at the value of $0 to decide which subcommand is actually being invoked, and then rewrite the argument list. Then each of these executables can call directly into the same entry point, without the need for further customization. The downside is that these executables will use up a lot of duplicate space on disk. Hopefully the users will be understanding. (Perhaps you could even do something where, upon the first invocation of each of these subcommands, they replace themselves on disk with a simpler script or symlink, which would reduce the disk space overhead eventually.)

Next, in order to actually have man find the man-pages at runtime, we need to adjust MANPATH, as mentioned above. There appears to be no direct configuration options under Git to set the lookup path for man. However, you can configure a different help viewer command. My idea so far to instead use env MANPATH=/path/to/man/pages: man as the man viewer command. (NB: the final colon is necessary for man to fall back on its regular search directories.) Or, if necessary, add yet another git-branchless subcommand which just delegates to man, but with the appropriate environment variables set.

As a part of doing all this, it would be nice to refactor the Git configuration to use an include directive pointing to a config file under .git/branchless. Then it would be really easy to inspect or remove the git-branchless-specific customization.

[jirutka]

It requires support from the system package manager.
Another is to request support from the system package manager.

That would be the right way to handle it on Linux, instead of inventing non-standard and clumsy workarounds. If the user build and install git-branchless manually, not via the system’s package manager, they can install the executable and man pages into /usr/local prefix (/usr/local/share/man/manX for the man pages) – that’s the standard way on *nix systems for decades. Another standard way is to install into $XDG_DATA_HOME prefix (by default $HOME/.local; $HOME/.local/share/man/manX for the man pages).

[arxanas]

@jirutka We also support Windows and NixOS; I don't know if those solutions would work there. There's also the problem of cleaning up old man-pages, since git-branchless is not stable and commands will probably be added and removed.