How can I provide help documentation for custom git commands?

Question

If I write a script called git-foo and drop it somewhere in my PATH , then I can run git foo to execute this script and run git foo --option argument to pass command line parameters and arguments for my script.

This syntactic sugar is destroyed when you try to print reference documentation. I did git-foo --help , but if I ran git foo --help , git did not move --help to my script and instead tries to open the man page for git-foo . I do not want this. Is there a way to suppress this behavior for custom commands? (Ideal as the author of the script, but I am willing to agree to a way to suppress this as a user.)

I suspect that I have to create a man page, but it seems rather burdensome: then the script will need to be packaged with an additional file, and the additional file will need to be installed somewhere else, and then uninstalling will have more work.

Answer 1

I think you're stuck. Git intentionally implements --help through man pages to ensure that there is only one source of information (as opposed to the fact that man pages do not synchronize with the built-in help output).

If you are writing a man page, you must install it in the man directory at the same level as the bin directory in which you installed the script.

Installing and removing one additional file does not seem too bad. Or you can just stick

 git-foo --help 

and ask people to use it.