Almost all Go binaries come without any man page, even when properly installed through means like Homebrew.

goman substitutes the missing man page by the README file from the Go binary's sources.

goman first grabs the source path from the binary. Then it tries to locate the README file locally via the GOPATH. If this fails, it tries to fetch the README file from the binary's public repository.

For that last option, goman makes a couple of assumptions about the location, but at least with github and gitlab, those assumptions should be valid.

Featured on episode #51 of the Go Time podcast! (In the "Free Software Friday" section, at 1:02:35)

goman <go binary file>

goman <go binary file> | less -R

(-R tells less to render ANSI color codes.)

go get -u github.com/christophberger/goman

goman can blend in with the standard man command. Bash example (to be placed in ~/.bashrc):

man() { 
    if ! /usr/bin/man $1; then 
        goman $1 | less -R; 
    fi; 
}

On macOS, ensure to source ~/.bashrc at the end of ~/.bash_profile, as the Terminal app starts all shells as login shells that do not read .bashrc. (Background information on this is available here or here or via search engines.)
(Adding this script directly to ~/.bash_profile is perhaps not a good idea as some interactive shells may start as non-login shells and therefore do not source ~/.bash_profile.)

All code written by myself is governed by a 3-clause BSD license, see LICENSE.txt.

The which package is part of the which command that is licensed under the MIT license; see LICENSE.which.txt.

The code that extracts the source code path from a go binary is a part of the gorebuild tool that is published under the MIT license; See LICENSE.dwarf.go.txt.

The Markdown renderer is a fork of blackfriday with extra code for rendering Markdown to plain text with ANSI color codes. See LICENSE.blackfriday.txt and the copyright notice in ec1oud/blackfriday/ansi.go.

In its current state, goman is little more than a proof of concept. Bugs certainly do exist, as well as functional shortcomings due to oversimplified design, such as:

• goman assumes that the README file contains either Markdown text or plain text. I know of at least one README.md that contains HTML. goman does not treat such cases in any special way.

• If a binary originates from a command subdirectory of a project, chances are that this subdirectory contains no extra README file. goman then tries to find the README file in the parent directories.

• Some binaries contain an absolute path to their source code, and goman assumes that the GOPATH used at compile time is the part from the root to the first directory named /src/. If the GOPATH itself contains a /src/ directory (e.g., "export GOPATH=/home/user/src/go"), goman fails extracting the relative source code path.

• goman's output may wrap character-wise instead of word-wise.

• Path redirection to canonical paths (like, e.g. from "https://npf.io/gorram" to https://github.com/natefinch/gorram) are not handled right now.

mdcat - a cat tool for Markdown

mandown - write real man pages in Markdown

mango - generate man pages from your source code

gorebuild - rebuild Go binaries from source

binstale - check if your go binaries are outdated

bin and gobin - update all your Go binaries

Fix stripping prefix from absolute path on Windows (PR #5)

Add support for the PE file format (Windows). (Implements issue #3)

Change search strategy for README file to cover all possible cases. (Fixes issue #2)

Fix slice panic if URL path is shorter than "github.com" (issue #1)