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

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(-)