Re: [PATCH v4] git remote: Separate usage strings for subcommands

[Nanako Shiraishi <nanako3@lavabit.com>]

Quoting Tim Henigan <tim.henigan@gmail.com>

> When the usage string for a subcommand must be printed,
> only print the information relevant to that command.

I think this is a huge improvement.

> diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
> index 82a3d29..ee3dc80 100644
> --- a/Documentation/git-remote.txt
> +++ b/Documentation/git-remote.txt
> @@ -9,14 +9,14 @@ git-remote - manage set of tracked repositories
>  SYNOPSIS
>  --------
>  [verse]
> -'git remote' [-v | --verbose]
> -'git remote add' [-t <branch>] [-m <master>] [-f] [--mirror] <name> <url>
> +'git remote' [<options>]
> +'git remote add' [<options>] <name> <url>
>  'git remote rename' <old> <new>
>  'git remote rm' <name>
> -'git remote set-head' <name> [-a | -d | <branch>]
> -'git remote show' [-n] <name>
> -'git remote prune' [-n | --dry-run] <name>
> -'git remote update' [-p | --prune] [group | remote]...
> +'git remote set-head' <name> [<options>] [-a | -d | <branch>]
> +'git remote show' [<options>] <name>
> +'git remote prune' [<options>] <name>
> +'git remote update' [<options>] [<group> | <remote>]...

Often people look at this part of the manual page to quickly remind 
themselves what options are available, and it is better to keep the 
current text. Some manual pages have to use [options...] when there 
are too many to list, but each subcommand of git-remote doesn't have 
that many options.

> diff --git a/builtin-remote.c b/builtin-remote.c
> index 0777dd7..24a3ec0 100644
> --- a/builtin-remote.c
> +++ b/builtin-remote.c
> @@ -7,18 +7,35 @@
>  #include "run-command.h"
>  #include "refs.h"
>  
> +#define REMOTE_BARE_USAGE "git remote [<options>]"
> +#define REMOTE_ADD_USAGE "git remote add [<options>] <name> <url>"
> +#define REMOTE_RENAME_USAGE "git remote rename <old> <new>"
> +#define REMOTE_RM_USAGE "git remote rm <name>"
> +#define REMOTE_SETHEAD_USAGE "git remote set-head <name> [-a | -d | <branch>]"
> +#define REMOTE_SHOW_USAGE "git remote show [<options>] <name>"
> +#define REMOTE_PRUNE_USAGE "git remote prune [<options>] <name>"
> +#define REMOTE_UPDATE_USAGE "git remote update [<options>] [<group> | <remote>]..."
> +
>  static const char * const builtin_remote_usage[] = {
> -	"git remote [-v | --verbose]",
> -	"git remote add [-t <branch>] [-m <master>] [-f] [--mirror] <name> <url>",
> -	"git remote rename <old> <new>",
> -	"git remote rm <name>",
> -	"git remote set-head <name> [-a | -d | <branch>]",
> -	"git remote show [-n] <name>",
> -	"git remote prune [-n | --dry-run] <name>",
> -	"git remote [-v | --verbose] update [-p | --prune] [group]",
> +	REMOTE_BARE_USAGE,
> +	REMOTE_ADD_USAGE,
> +	REMOTE_RENAME_USAGE,
> +	REMOTE_RM_USAGE,
> +	REMOTE_SETHEAD_USAGE,
> +	REMOTE_SHOW_USAGE,
> +	REMOTE_PRUNE_USAGE,
> +	REMOTE_UPDATE_USAGE,
>  	NULL
>  };

For the same reason, I don't think this is a good change, if these
lines are used to show the first lines of 'git-remote -h' output.