rev-parse --parseopt: option argument name hints

Built-in commands can specify names for option arguments when usage text
is generated for a command.  sh based commands should be able to do the
same.

Option argument name hint is any text that comes after [*=?!] after the
argument name up to the first whitespace.

Signed-off-by: Ilya Bobyr <ilya.bobyr@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
t1502: protect runs of SPs used in the indentation

The expected output from the argument help use runs of SPs to align
the description of each option; a careless use of --whitespace=fix
can turn leading parts of them into appropriate number of HTs.
Prevent such a breakage by prefixing all the expected lines with
leading vertical bars in the original and stripping them with a
small sed script.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
parse-options: multi-word argh should use dash to separate words

"When you need to use space, use dash" is a strange way to say that
you must not use a space.  By convention, most of the command line
descriptions use dashed-multi-words, and technically, you do not
even need or want to use spaces in these places---you should be
spelling your multi-word-parameters with words separated with
dashes.  Rephrase the documentation to avoid this strangeness.

Fix a few existing multi-word argument help strings, i.e.

 - GPG key-ids given to -S/--gpg-sign are "key-id";
 - Refs used for storing notes are "notes-ref"; and
 - Expiry timestamps given to --expire are "expiry-date".

Signed-off-by: Junio C Hamano <gitster@pobox.com>
update-index: teach --cacheinfo a new syntax mode,sha1,path

The "--cacheinfo" option is very unusual in that it takes three
option parameters.  An option with an optional parameter is bad
enough.  An option with multiple parameters is simply insane.

Introduce a new syntax that takes these three things concatenated
together with a comma, which makes the command line syntax more
uniform across subcommands, while retaining the traditional syntax
for backward compatiblity.

If we were designing the "update-index" subcommand from scratch
today, it may probably have made sense to make this option (and
possibly others) a command mode option that does not take any option
parameter (hence no need for arg-help).  But we do not live in such
an ideal world, and as far as I can tell, the command still supports
(and must support) mixed command modes in a single invocation, e.g.

    $ git update-index path1 --add path2 \
        --cacheinfo 100644 $(git hash-object --stdin -w <path3) path3 \
	path4

must make sure path1 is already in the index and update all of these
four paths.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
parse-options: make sure argh string does not have SP or _

We encourage an argument hint that consists of multiple words to be
spelled as a single-token separated with dashes.  In order to help
catching violations added by new users of parse-options, make sure
argh does not contain SP or _ when the code validates the option
definitions.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
Merge branch 'ib/rev-parse-parseopt-argh' into jch

* ib/rev-parse-parseopt-argh:
  parse-options: make sure argh string does not have SP or _
  update-index: teach --cacheinfo a new syntax mode,sha1,path
  parse-options: multi-word argh should use dash to separate words
  t1502: protect runs of SPs used in the indentation
  rev-parse --parseopt: option argument name hints
Merge branch 'nd/log-show-linear-break' into pu

Attempts to show where a single-strand-of-pearls break in "git log"
output.

The implementation seems to have got worse compared to the previous
round.  Will hold.

* nd/log-show-linear-break:
  log: add --show-linear-break to help see non-linear history
  object.h: centralize object flag allocation
Merge branch 'jk/branch-at-publish-rebased' into pu

Give an easier access to the tracking branches from "other" side in
a triangular workflow by introducing B@{publish} that works in a
similar way to how B@{upstream} does.

Meant to be used as a basis for whatever Ram wants to build on.

Will hold.

* jk/branch-at-publish-rebased:
  t1507 (rev-parse-upstream): fix typo in test title
  implement @{publish} shorthand
  branch_get: provide per-branch pushremote pointers
  branch_get: return early on error
  sha1_name: refactor upstream_mark

# Conflicts:
# 	remote.c
Merge branch 'po/everyday-doc' into pu

This may make the said command to emit something, but the source is
not meant to be formatted into a manual pages to begin with, and
also its contents are a bit stale.  It may be a good first step in
the right direction, but needs more work to at least get the
mark-up right before public consumption.

Will hold.

* po/everyday-doc:
  Make 'git help everyday' work

# Conflicts:
# 	Documentation/Makefile
Merge branch 'jl/submodule-recursive-checkout' into pu

* jl/submodule-recursive-checkout:
  Teach checkout to recursively checkout submodules
  submodule: teach unpack_trees() to update submodules
  submodule: teach unpack_trees() to repopulate submodules
  submodule: teach unpack_trees() to remove submodule contents
  submodule: prepare for recursive checkout of submodules
Merge branch 'hv/submodule-ignore-fix' into pu

Teach "git add" to be consistent with "git status" when changes to
submodules are set to be ignored, to avoid surprises after checking
with "git status" to see there isn't any change to be further added
and then see that "git add ." adds changes to them.

I think a reroll is coming, so this may need to be replaced, but I
needed some practice with heavy conflict resolution.  It conflicts
with two changes to "git add" that have been scheduled for Git 2.0
quite badly, and I think I got the resolution right this time.

* hv/submodule-ignore-fix:
  disable complete ignorance of submodules for index <-> HEAD diff
  always show committed submodules in summary after commit
  teach add -f option for ignored submodules
  fix 'git add' to skip submodules configured as ignored
Merge branch 'rb/merge-prepare-commit-msg-hook' into pu

Expose more merge states (e.g. $GIT_DIR/MERGE_MODE) to hooks that
run during "git merge".  The log message stresses too much on one
hook, prepare-commit-msg, but it would equally apply to other hooks
like post-merge, I think.

* rb/merge-prepare-commit-msg-hook:
  merge: drop unused arg from abort_commit method signature
  merge: make prepare_to_commit responsible for write_merge_state
  t7505: ensure cleanup after hook blocks merge
  t7505: add missing &&

# Conflicts:
# 	builtin/merge.c
# 	t/t7505-prepare-commit-msg-hook.sh
Merge branch 'cc/interpret-trailers' into pu

A new filter to programatically edit the tail end of the commit log
messages.

* cc/interpret-trailers:
  Documentation: add documentation for 'git interpret-trailers'
  trailer: add tests for commands in config file
  trailer: execute command from 'trailer.<name>.command'
  trailer: add tests for "git interpret-trailers"
  trailer: add interpret-trailers command
  trailer: put all the processing together and print
  trailer: parse trailers from stdin
  trailer: process command line trailer arguments
  trailer: read and process config information
  trailer: process trailers from stdin and arguments
  trailers: add data structures and basic functions
Merge branch 'kb/fast-hashmap-pack-struct' into pu

I am inclined to drop this; an alternative is to replace it with
the "more portable" one that uses #pragma, which I am willing to
try doing so on 'pu', though.

* kb/fast-hashmap-pack-struct:
  hashmap.h: make sure map entries are tightly packed
Merge branch 'jc/format-patch' into pu

A new option to send a single patch to the standard output to be
appended at the bottom of a message.  I personally have no need for
this, but it was easy enough to cobble together.  Tests, docs and
stripping out more MIMEy stuff are left as exercises to interested
parties.

* jc/format-patch:
  format-patch: --inline-single
  format-patch: rename "no_inline" field

# Conflicts:
# 	builtin/log.c
# 	log-tree.c
# 	pretty.c
Merge branch 'jc/show-branch' into pu

* jc/show-branch:
  show-branch: use commit slab to represent bitflags of arbitrary width
  show-branch.c: remove "all_mask"
  show-branch.c: abstract out "flags" operation
  show-branch.c: lift all_mask/all_revs to a global static
  show-branch.c: update comment style

# Conflicts:
# 	builtin/show-branch.c
Merge branch 'tr/merge-recursive-index-only' into pu

Will hold.

* tr/merge-recursive-index-only:
  merge-recursive: -Xindex-only to leave worktree unchanged
  merge-recursive: internal flag to avoid touching the worktree
  merge-recursive: remove dead conditional in update_stages()
Merge branch 'tg/perf-lib-test-perf-cleanup' into pu

Add test_perf_cleanup shell function to the perf suite, that allows
the script writers to define a test with a clean-up action.

Will hold.

* tg/perf-lib-test-perf-cleanup:
  perf-lib: add test_perf_cleanup target
  perf-lib: split starting the test from the execution
Merge branch 'bc/blame-crlf-test' into pu

I have a feeling that a fix for this should be fairly isolated and
trivial (it should be just the matter of paying attention to the
crlf settings when synthesizing the fake commit)---perhaps somebody
can squash in a fix to this?

* bc/blame-crlf-test:
  blame: add a failing test for a CRLF issue.
Merge branch 'as/grep-fullname-config' into pu

* as/grep-fullname-config:
  grep: add grep.fullName config variable