[PATCH 0/3] Parse-options: spell multi-word placeholders with dashes

[Junio C Hamano <gitster@pobox.com>]

This is a follow-up to Ilya's 4th round of letting scripted
porcelains to give argv-help to their users with their command line
option parser based on "rev-parse --parseopt".

While reviewing the patch, we found that a few options to the
built-in commands were described with an argv-help (the placeholder
for an option parameter, e.g. "key-id" in "--gpg-sign <key-id>")
that has multiple words to decribe a single entity, spelling these
multiple words separated in spaces.  It is more customary to spell a
multi-word parameter with dashes, and the first patch in series is
about making it so.

During the course of the development of the first patch, I needed a
mechanical way to catch existing offenders; the last patch teaches
the parse-options API implementation to find argv-help strings that
contain SP or underscore.

There is one glitch, though.  "update-index --cacheinfo" option
takes THREE parameters: mode, sha1, and path.  Because a command
line option that takes multiple options is very unusual, the second
patch introduces a new syntax to pass these three items as a single
parameter to "--cacheinfo" option, which brings our command line
argument convention more uniform and consistent.  We however cannot
deprecate or remove the traditional syntax, so it is still kept as
an alternative "backward compatibility" syntax.

Junio C Hamano (3):
  parse-options: multi-word argh should use dash to separate words
  update-index: teach --cacheinfo a new syntax "mode,sha1,path"
  parse-options: make sure argh string does not have SP or _

 Documentation/git-cherry-pick.txt  |  6 +++---
 Documentation/git-commit.txt       |  2 +-
 Documentation/git-merge.txt        |  2 +-
 Documentation/git-notes.txt        |  2 +-
 Documentation/git-rev-parse.txt    | 16 ++++++++--------
 Documentation/git-revert.txt       |  6 +++---
 Documentation/git-update-index.txt |  8 ++++++--
 builtin/checkout.c                 |  2 +-
 builtin/commit.c                   |  2 +-
 builtin/merge.c                    |  2 +-
 builtin/notes.c                    |  2 +-
 builtin/revert.c                   |  2 +-
 builtin/tag.c                      |  2 +-
 builtin/update-index.c             | 34 +++++++++++++++++++++++++++++++---
 parse-options.c                    |  3 +++
 parse-options.h                    |  2 +-
 t/t2107-update-index-basic.sh      | 13 +++++++++++++
 17 files changed, 77 insertions(+), 29 deletions(-)

-- 
1.9.1-471-gcccbd8b