53

So it seems that typing man git init into a bash prompt on an Ubuntu 14.04 system does the same as man git-init, only I'm not quite sure how.

The man page for man (i.e. man man) doesn't seem to allow for this construct, unless git was a section of the manual, but the man page seems to come from section 1.

Is this an undocumented usage supported by man? Have I misunderstood the documentation of man? Is some other magic happening? Anyone care to explain?

mc0e
  • 1,086

1 Answers1

72

Some implementations of man, including the one used by Ubuntu, replace spaces in its search terms with hyphens and attempt to find a manual page under that name. So man git init looks for the same thing as man git-init. Similarly, man run parts and man ntfs 3g work (if you have run-parts and ntfs-3g on your system).

It only does this with word pairs, though, so man git annex sync does not work (though man git-annex sync does, as that's again a word pair).

In fact, when you ask for two manual pages (e.g., man git bash to see both the git and bash manpages), man actually first tries to look for a git-bash manpage. You can see this in the debug output if you enable it with -d.

This man feature is called "subpages" you can read the source code implementing subpages in man-db (thanks, Stephen Kitt). Searching the man(1) manpage for "subpages" will also lead you to the description of this behavior under the --no-subpages option:

--no-subpages
      By default, man will try to interpret pairs of manual page
      names given on the command line as equivalent to a single
      manual page name containing a hyphen or an underscore.  This
      supports the common pattern of programs that implement a
      number of subcommands, allowing them to provide manual pages
      for each that can be accessed using similar syntax as would be
      used to invoke the subcommands themselves.  For example:

        $ man -aw git diff
        /usr/share/man/man1/git-diff.1.gz

      To disable this behaviour, use the --no-subpages option.

        $ man -aw --no-subpages git diff
        /usr/share/man/man1/git.1.gz
        /usr/share/man/man3/Git.3pm.gz
        /usr/share/man/man1/diff.1.gz
Wieland
  • 6,489
derobert
  • 109,670
  • This seems to not work on CentOS 6.6. Is it Ubuntu only? – Wildcard Feb 23 '16 at 21:59
  • 1
    @Wildcard which part seems to not work? It should work as long as CentOS is using man-db (there are other man implementations), and subpages haven't been disabled (e.g., with --no-subpages). I'm using Debian, so it definitely isn't just Ubuntu. – derobert Feb 23 '16 at 23:06
  • 2
    The important thing is that this is unique to a specific implementation of man. It is by no means universal or particular common. – chepner Feb 24 '16 at 15:25