submodule update: add --remote for submodule's upstream changes

The current `update` command incorporates the superproject's gitlinked
SHA-1 ($sha1) into the submodule HEAD ($subsha1).  Depending on the
options you use, it may checkout $sha1, rebase the $subsha1 onto
$sha1, or merge $sha1 into $subsha1.  This helps you keep up with
changes in the upstream superproject.

However, it's also useful to stay up to date with changes in the
upstream subproject.  Previous workflows for incorporating such
changes include the ungainly:

  $ git submodule foreach 'git checkout $(git config --file $toplevel/.gitmodules submodule.$name.branch) && git pull'

With this patch, all of the useful functionality for incorporating
superproject changes can be reused to incorporate upstream subproject
updates.  When you specify --remote, the target $sha1 is replaced with
a $sha1 of the submodule's origin/master tracking branch.  If you want
to merge a different tracking branch, you can configure the
`submodule.<name>.branch` option in `.gitmodules`.  You can override
the `.gitmodules` configuration setting for a particular superproject
by configuring the option in that superproject's default configuration
(using the usual configuration hierarchy, e.g. `.git/config`,
`~/.gitconfig`, etc.).

Previous use of submodule.<name>.branch
=======================================

Because we're adding a new configuration option, it's a good idea to
check if anyone else is already using the option.  The foreach-pull
example above was described by Ævar in

  commit f030c96d8643fa0a1a9b2bd9c2f36a77721fb61f
  Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
  Date:   Fri May 21 16:10:10 2010 +0000

    git-submodule foreach: Add $toplevel variable

Gerrit uses the same interpretation for the setting, but because
Gerrit has direct access to the subproject repositories, it updates
the superproject repositories automatically when a subproject changes.
Gerrit also accepts the special value '.', which it expands into the
superproject's branch name.

Although the --remote functionality is using `submodule.<name>.branch`
slightly differently, the effect is the same.  The foreach-pull
example uses the option to record the name of the local branch to
checkout before pulls.  The tracking branch to be pulled is recorded
in `.git/modules/<name>/config`, which was initialized by the module
clone during `submodule add` or `submodule init`.  Because the branch
name stored in `submodule.<name>.branch` was likely the same as the
branch name used during the initial `submodule add`, the same branch
will be pulled in each workflow.

Implementation details
======================

In order to ensure a current tracking branch state, `update --remote`
fetches the submodule's remote repository before calculating the
SHA-1.  However, I didn't change the logic guarding the existing fetch:

  if test -z "$nofetch"
  then
    # Run fetch only if $sha1 isn't present or it
    # is not reachable from a ref.
    (clear_local_git_env; cd "$path" &&
      ( (rev=$(git rev-list -n 1 $sha1 --not --all 2>/dev/null) &&
       test -z "$rev") || git-fetch)) ||
    die "$(eval_gettext "Unable to fetch in submodule path '\$path'")"
  fi

There will not be a double-fetch, because the new $sha1 determined
after the `--remote` triggered fetch should always exist in the
repository.  If it doesn't, it's because some racy process removed it
from the submodule's repository and we *should* be re-fetching.

Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
submodule add: If --branch is given, record it in .gitmodules

This allows you to easily record a submodule.<name>.branch option in
.gitmodules when you add a new submodule.  With this patch,

  $ git submodule add -b <branch> <repository> [<path>]
  $ git config -f .gitmodules submodule.<path>.branch <branch>

reduces to

  $ git submodule add -b <branch> <repository> [<path>]

This means that future calls to

  $ git submodule update --remote ...

will get updates from the same branch that you used to initialize the
submodule, which is usually what you want.

Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
compat/fnmatch: update old-style definition to ANSI

We try to avoid touching borrowed code, but we encourage people to
write without old-style definition and compile with -Werror these
days, and on platforms that need to use NO_FNMATCH, these three
functions make the compilation fail.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
Merge branch 'sl/git-svn-docs' into jch

Will cook in 'next'.

* sl/git-svn-docs:
  git-svn: Note about tags.
  git-svn: Expand documentation for --follow-parent
  git-svn: Recommend use of structure options.
  git-svn: Document branches with at-sign(@).
Merge branch 'nd/index-format-doc' into jch

* nd/index-format-doc:
  index-format.txt: clarify what is "invalid"
Merge branch 'jc/fetch-tags-doc' into jch

The explanation for "fetch --tags" was actually talking more about
"fetch --no-tags".  Clariify what "--tags" really means.

* jc/fetch-tags-doc:
  fetch --tags: clarify documentation
Merge branch 'sl/readme-gplv2' into jch

Clarify that the project as a whole is GPLv2 only, with some parts
borrowed under different licenses that are compatible with GPLv2.

* sl/readme-gplv2:
  README: it does not matter who the current maintainer is
  README: Git is released under the GPLv2, not just "the GPL"
Merge branch 'as/doc-for-devs' into jch

It might be a better idea to move the text the bottom one adds to
the extended description from the quick checklist part.

* as/doc-for-devs:
  Documentation: move support for old compilers to CodingGuidelines
  SubmittingPatches: add convention of prefixing commit messages
Merge branch 'jk/avoid-mailto-invalid-in-doc' into jch

Avoids invalid sample e-mail addresses from becoming mailto links
in the formatted output, which by itself is "Meh" for me (who
cares?).
It highlights some issues with ``pretty quotes''; AsciiDoc 8.5.2
seems to have problems with the construct.

* jk/avoid-mailto-invalid-in-doc:
  Documentation: don't link to example mail addresses
Merge branch 'ta/api-index-doc' into jch

Will merge to 'master'.

* ta/api-index-doc:
  Remove misleading date from api-index-skel.txt
Merge branch 'cr/doc-checkout-branch' into jch

Document the magic "git checkout <no-such-branch>" hack to create
local branch out of a remote tracking branch that hasn't been
documented so far.

Will merge to 'next'.

* cr/doc-checkout-branch:
  Documentation/git-checkout.txt: document 70c9ac2 behavior
  Documentation/git-checkout.txt: clarify usage
Merge branch 'jc/doc-diff-blobs' into jch

"git diff <blob> <blob>" was not documented and was only hinted as
an extension to "git diff <commit> <commit> -- <pathspec>", but
comparison between two blobs are more special than that.  It does
not take any pathspec to begin with.

* jc/doc-diff-blobs:
  Documentation: Describe "git diff <blob> <blob>" separately
Merge branch 'sp/shortlog-missing-lf' into jch

When a line to be wrapped has a solid run of non space characters
whose length exactly is the wrap width, "git shortlog -w" failed to
add a newline after such a line.

Will cook in 'next'.

* sp/shortlog-missing-lf:
  strbuf_add_wrapped*(): Remove unused return value
  shortlog: fix wrapping lines of wraplen
Merge branch 'jc/maint-fbsd-sh-ifs-workaround' into jch

Will cook in 'next'.

* jc/maint-fbsd-sh-ifs-workaround:
  sh-setup: work around "unset IFS" bug in some shells
Merge branch 'jc/apply-trailing-blank-removal' into jch

Fix to update_pre_post_images() that did not take into account the
possibility that whitespace fix could shrink the preimage and
change the number of lines in it.

Will cook in 'next'.

* jc/apply-trailing-blank-removal:
  apply.c:update_pre_post_images(): the preimage can be truncated
Merge branch 'mh/ceiling' into jch

Elements of GIT_CEILING_DIRECTORIES list may not match the real
pathname we obtain from getcwd(), leading the GIT_DIR discovery
logic to escape the ceilings the user thought to have specified.

Resurrected from Stalled; the earlier performance fear was
unwarranted.

Will cook in 'next'.

* mh/ceiling:
  string_list_longest_prefix(): remove function
  setup_git_directory_gently_1(): resolve symlinks in ceiling paths
  longest_ancestor_length(): require prefix list entries to be normalized
  longest_ancestor_length(): take a string_list argument for prefixes
  longest_ancestor_length(): use string_list_split()
  Introduce new function real_path_if_valid()
  real_path_internal(): add comment explaining use of cwd
  Introduce new static function real_path_internal()

Conflicts:
	Documentation/technical/api-string-list.txt
	string-list.c
	string-list.h
Merge branch 'nd/wildmatch' into jch

Allows pathname patterns in .gitignore and .gitattributes files
with double-asterisks "foo/**/bar" to match any number of directory
hierarchies.

I suspect that this needs to be plugged to pathspec matching code;
otherwise "git log -- 'Docum*/**/*.txt'" would not show the log for
commits that touch Documentation/git.txt, which would be confusing
to the users.

Will cook in 'next'.

* nd/wildmatch:
  t3070: Disable some failing fnmatch tests
  test-wildmatch: avoid Windows path mangling
  Support "**" wildcard in .gitignore and .gitattributes
  wildmatch: make /**/ match zero or more directories
  wildmatch: adjust "**" behavior
  wildmatch: fix case-insensitive matching
  wildmatch: remove static variable force_lower_case
  wildmatch: make wildmatch's return value compatible with fnmatch
  t3070: disable unreliable fnmatch tests
  Integrate wildmatch to git
  wildmatch: follow Git's coding convention
  wildmatch: remove unnecessary functions
  Import wildmatch from rsync
  ctype: support iscntrl, ispunct, isxdigit and isprint
  ctype: make sane_ctype[] const array

Conflicts:
	Makefile
Merge branch 'rc/maint-complete-git-p4' into jch

Comment from Pete will need to be addressed in a follow-up patch.

* rc/maint-complete-git-p4:
  Teach git-completion about git p4
Merge branch 'mh/pthreads-autoconf' into jch

Will cook in 'next'.

* mh/pthreads-autoconf:
  configure.ac: fix pthreads detection on Mac OS X
Merge branch 'jk/fsck-dot-in-trees' into jch

Will cook in 'next'.

* jk/fsck-dot-in-trees:
  fsck: warn about ".git" in trees
  fsck: warn about '.' and '..' in trees