submodule: Make 'checkout' update_module explicit

This avoids the current awkwardness of having either '' or 'checkout'
for checkout-mode updates, which makes testing for checkout-mode
updates (or non-checkout-mode updates) easier.

Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
submodule: Document module_clone arguments in comments

Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
submodule: Explicit local branch creation in module_clone

The previous code only checked out branches in cmd_add.  This commit
moves the branch-checkout logic into module_clone, where it can be
shared by cmd_add and cmd_update.  I also update the initial checkout
command to use 'reset' to preserve branches setup during module_clone.

With this change, folks cloning submodules for the first time via:

  $ git submodule update ...

will get a local branch instead of a detached HEAD, unless they are
using the default checkout-mode updates.  This is a change from the
previous situation where cmd_update always used checkout-mode logic
(regardless of the requested update mode) for updates that triggered
an initial clone, which always resulted in a detached HEAD.

This commit does not change the logic for updates after the initial
clone, which will continue to create detached HEADs for checkout-mode
updates, and integrate remote work with the local HEAD (detached or
not) in other modes.

The motivation for the change is that developers doing local work
inside the submodule are likely to select a non-checkout-mode for
updates so their local work is integrated with upstream work.
Developers who are not doing local submodule work stick with
checkout-mode updates so any apparently local work is blown away
during updates.  For example, if upstream rolls back the remote branch
or gitlinked commit to an earlier version, the checkout-mode developer
wants their old submodule checkout to be rolled back as well, instead
of getting a no-op merge/rebase with the rolled-back reference.

By using the update mode to distinguish submodule developers from
black-box submodule consumers, we can setup local branches for the
developers who will want local branches, and stick with detached HEADs
for the developers that don't care.

Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
[DONOTMERGE] t7406: Just-cloned checkouts update to the gitlinked hash with 'reset'

To preserve the local branch, for situations where we're not on a
detached HEAD.

*** This addresses the fallout from the previous commit that changes
    the behaviour, and should be squashed to it.

Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
t7406: Add explicit tests for head attachement after cloning updates

Test that cloning updates checkout the appropriate local branch for
their update-mode:

* Checkout-mode updates get detached HEADs
* Everyone else gets a local branch, matching the configured
  submodule.<name>.branch and defaulting to master.

The 'initial-setup' tag makes it easy to reset the superproject to a
known state, as several earlier tests commit to submodules and commit
the changed gitlinks to the superproject, but don't push the new
submodule commits to the upstream subprojects.  This makes it
impossible to checkout the current super master, because it references
submodule commits that don't exist in the upstream subprojects.  For a
specific example, see the tests that currently generate the
'two_new_submodule_commits' commits.

Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Documentation: Describe 'submodule update' modes in detail

The old documentation did not distinguish between cloning and
non-cloning updates and lacked clarity on which operations would lead
to detached HEADs, and which would not.  The new documentation
addresses these issues while updating the docs to reflect the changes
introduced by this branch's explicit local branch creation in
module_clone.

I also add '--checkout' to the usage summary and group the update-mode
options into a single set.

Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Merge branch 'wk/submodule-on-branch' into pu

* wk/submodule-on-branch:
  Documentation: Describe 'submodule update' modes in detail
  t7406: Add explicit tests for head attachement after cloning updates
  [DONOTMERGE] t7406: Just-cloned checkouts update to the gitlinked hash with 'reset'
  submodule: Explicit local branch creation in module_clone
  submodule: Document module_clone arguments in comments
  submodule: Make 'checkout' update_module explicit

# Conflicts:
# 	t/t7406-submodule-update.sh
Merge branch 'mh/safe-create-leading-directories' into pu

Code clean-up and protection against concurrent write access to the
ref namespace.

Asked Michael and Sebastian to work together to roll the latter's
"allow passing p\a\t\h to safe_create_leading_dir()" into this.

* mh/safe-create-leading-directories:
  rename_tmp_log(): on SCLD_VANISHED, retry
  rename_tmp_log(): limit the number of remote_empty_directories() attempts
  rename_tmp_log(): handle a possible mkdir/rmdir race
  rename_ref(): extract function rename_tmp_log()
  remove_dir_recurse(): handle disappearing files and directories
  remove_dir_recurse(): tighten condition for removing unreadable dir
  lock_ref_sha1_basic(): if locking fails with ENOENT, retry
  lock_ref_sha1_basic(): on SCLD_VANISHED, retry
  safe_create_leading_directories(): add new error value SCLD_VANISHED
  cmd_init_db(): when creating directories, handle errors conservatively
  safe_create_leading_directories(): introduce enum for return values
  safe_create_leading_directories(): always restore slash at end of loop
  safe_create_leading_directories(): split on first of multiple slashes
  safe_create_leading_directories(): rename local variable
  safe_create_leading_directories(): add explicit "slash" pointer
  safe_create_leading_directories(): reduce scope of local variable
  safe_create_leading_directories(): fix format of "if" chaining
Merge branch 'ss/safe-create-leading-dir-with-slash' into pu

* ss/safe-create-leading-dir-with-slash:
  safe_create_leading_directories(): on Windows, \ can separate path components

# Conflicts:
# 	sha1_file.c
Merge branch 'kb/fast-hashmap' into pu

Improvements to our hash table to get it to meet the needs of the
msysgit fscache project, with some nice performance improvements.

The tip one does not seem to have reached concensus (yet).

* kb/fast-hashmap:
  hashmap.h: make sure map entries are tightly packed
Merge branch 'rv/send-email-cache-generated-mid' into pu

* rv/send-email-cache-generated-mid:
  git-send-email: Cache generated message-ids, use them when prompting
  git-send-email: add optional 'choices' parameter to the ask sub
Merge branch 'jk/gitweb-utf8' into pu

Various fixes to gitweb.

Drew Northup volunteered to take a look into this.
$gmane/226216

* jk/gitweb-utf8:
  gitweb: Fix broken blob action parameters on blob/commitdiff pages
  gitweb: Don't append ';js=(0|1)' to external links
  gitweb: Make feed title valid utf8
  gitweb: Fix utf8 encoding for blob_plain, blobdiff_plain, commitdiff_plain, and patch
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 'rj/read-default-config-in-show-ref-pack-refs' into pu

The changes themselves are probably good, but it is unclear what
basic setting needs to be read for which exact operation.

$gmane/228294

* rj/read-default-config-in-show-ref-pack-refs:
  ### DONTMERGE: needs better explanation on what config they need
  pack-refs.c: Add missing call to git_config()
  show-ref.c: Add missing call to git_config()
Merge branch 'tr/merge-recursive-index-only' into pu

Will hold until using script appears.

* 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.

Holding until needed.

* tg/perf-lib-test-perf-cleanup:
  perf-lib: add test_perf_cleanup target
  perf-lib: split starting the test from the execution
Merge branch 'yt/shortened-rename' into pu

Attempts to give more weight on the fact that a filepair represents
a rename than showing substring of the actual path when diffstat
lines are not wide enough.

I am not sure if that is solving a right problem, though.

* yt/shortened-rename:
  SQUASH??? style fixes and s/omit/shorten/ where appropriate
  diff.c: keep arrow(=>) on show_stats()'s shortened filename part to make rename visible
Merge branch 'jt/commit-fixes-footer' into pu

There is an ongoing discussion around this topic; in general I am
fairly negative on a new feature that is too narrow and prefer a
more generic solution that can be tailored for specific needs, as
many people stated in the thread.

It appears that the discussion stalled.

* jt/commit-fixes-footer:
  commit: Add -f, --fixes <commit> option to add Fixes: line
Merge branch 'jc/create-directories-microopt' into pu

Of unknown value until tested on non-Linux platforms (especially
Windows).

Will hold.

* jc/create-directories-microopt:
  checkout: most of the time we have good leading directories