makes life
easier for your user, who can skip to the section they know contains the
information they need.

NOTE: Before trying to build the docs, make sure you have the package `asciidoc`
installed.

Now that you've written your manpage, you'll need to build it explicitly. We
convert your AsciiDoc to troff which is man-readable like so:

----
$ make all doc
$ man Documentation/git-psuh.1
----

or

----
$ make -C Documentation/ git-psuh.1
$ man Documentation/git-psuh.1
----

While this isn't as satisfying as running through `git help`, you can at least
check that your help page looks right.

You can also check that the documentation coverage is good (that is, the project
sees that your command has been implemented as well as documented) by running
`make check-docs` from the top-level.

Go ahead and commit your new documentation change.

[[add-usage]]
=== Adding Usage Text

Try and run `./bin-wrappers/git psuh -h`. Your command should crash at the end.
That's because `-h` is a special case which your command should handle by
printing usage.

Take a look at `Documentation/technical/api-parse-options.adoc`. This is a handy
tool for pulling out options you need to be able to handle, and it takes a
usage string.

In order to use it, we'll need to prepare a NULL-terminated array of usage
strings and a `builtin_psuh_options` array.

Add a line to `#include "parse-options.h"`.

At global scope, add your array of usage strings:

----
static const char * const psuh_usage[] = {
	N_("git psuh [<arg>...]"),
	NULL,
};
----

Then, within your `cmd_psuh()` implementation, we can declare and populate our
`option` struct. Ours is pretty boring but you can add more to it if you want to
explore `parse_options()` in more detail:

----
	struct option options[] = {
		OPT_END()
	};
----

Finally, before you print your args and prefix, add the call to
`parse-options()`:

----
	argc = parse_options(argc, argv, prefix, options, psuh_usage, 0);
----

This call will modify your `argv` parameter. It will strip the options you
specified in `options` from `argv` and the locations pointed to from `options`
entries will be updated. Be sure to replace your `argc` with the result from
`parse_options()`, or you will be confused if you try to parse `argv` later.

It's worth noting the special argument `--`. As you may be aware, many Unix
commands use `--` to indicate "end of named parameters" - all parameters after
the `--` are interpreted merely as positional arguments. (This can be handy if
you want to pass as a parameter something which would usually be interpreted as
a flag.) `parse_options()` will terminate parsing when it reaches `--` and give
you the rest of the options afterwards, untouched.

Now that you have a usage hint, you can teach Git how to show it in the general
command list shown by `git help git` or `git help -a`, which is generated from
`command-list.txt`. Find the line for 'git-pull' so you can add your 'git-psuh'
line above it in alphabetical order. Now, we can add some attributes about the
command which impacts where it shows up in the aforementioned help commands. The
top of `command-list.txt` shares some information about what each attribute
means; in those help pages, the commands are sorted according to these
attributes. `git psuh` is user-facing, or porcelain - so we will mark it as
"mainporcelain". For "mainporcelain" commands, the comments at the top of
`command-list.txt` indicate we can also optionally add an attribute from another
list; since `git psuh` shows some information about the user's workspace but
doesn't modify anything, let's mark it as "info". Make sure to keep your
attributes in the same style as the rest of `command-list.txt` using spaces to
align and delineate them:

----
git-prune-packed                        plumbingmanipulators
git-psuh                                mainporcelain		info
git-pull                                mainporcelain           remote
git-push                                mainporcelain