Make it clear that there is no implicit floating going on; --remote
lets you explicitly integrate the upstream branch in your current
HEAD (just like running 'git pull' in the submodule).  The only
distinction with the current 'git pull' is the config location and
setting used for the upstream branch, which is hopefully clear now.
Signed-off-by: NW. Trevor King <wking@tremily.us>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

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.

Testing
=======

In t7406, just-cloned checkouts now update to the gitlinked hash with
'reset', to preserve the local branch for situations where we're not
on a detached HEAD.

I also added explicit tests to t7406 for HEAD attachement after
cloning updates, showing that it depends on 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.

Documentation
=============

I updated the docs to describe the '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 commit'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: NW. Trevor King <wking@tremily.us>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NW. Trevor King <wking@tremily.us>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

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: NW. Trevor King <wking@tremily.us>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

'checkout' is documented as one of the valid values for the
'submodule.<name>.update' variable, and in a repository with the
variable set to 'checkout', "git submodule update" command does
update using the 'checkout' mode.

However, it has been an accident that the implementation works this
way; any unknown value would trigger the same codepath and update
using the 'checkout' mode.

Explicitly list 'checkout' as one of the known update modes, and
error out when an unknown update mode is used.

Teach the codepath that initializes the configuration variable from
an in-tree .gitmodules that 'checkout' is one of the valid values.
The code since ac1fbbda (submodule: do not copy unknown update mode
from .gitmodules, 2013-12-02) used to treat the value 'checkout' as
unknown and mapped it to 'none', which made little sense.  With this
change, 'checkout' specified in .gitmodules will stay to be 'checkout'.
Signed-off-by: NFrancesco Pretto <ceztko@gmail.com>
Signed-off-by: NSigned-off-by: Junio C Hamano <gitster@pobox.com>

No code ever used this symbol since the command was introduced at
9f613ddd (Add git-for-each-ref: helper for language bindings,
2006-09-15).
Signed-off-by: NRamkumar Ramachandra <artagnon@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NJunio C Hamano <gitster@pobox.com>

* rs/doc-submitting-patches:
  SubmittingPatches: document how to handle multiple patches

* tr/doc-git-cherry:
  Documentation: revamp git-cherry(1)

* nd/glossary-content-pathspec-markup:
  glossary-content.txt: fix documentation of "**" patterns

* jj/doc-markup-gitcli:
  Documentation/gitcli.txt: fix double quotes

* jj/doc-markup-hints-in-coding-guidelines:
  State correct usage of literal examples in man pages in the coding standards

* jj/log-doc:
  Documentation/git-log.txt: mark-up fix and minor rephasing
  Documentation/git-log: update "--log-size" description

* jj/rev-list-options-doc:
  Documentation/rev-list-options.txt: fix some grammatical issues and typos
  Documentation/rev-list-options.txt: fix mark-up

* tb/doc-fetch-pack-url:
  git-fetch-pack uses URLs like git-fetch

* mi/typofixes:
  contrib: typofixes
  Documentation/technical/http-protocol.txt: typofixes
  typofixes: fix misspelt comments

Two processes creating loose objects at the same time could have
failed unnecessarily when the name of their new objects started
with the same byte value, due to a race condition.

* jh/loose-object-dirs-creation-race:
  sha1_file.c:create_tmpfile(): Fix race when creating loose object dirs

"git am --abort" sometimes complained about not being able to write
a tree with an 0{40} object in it.

* jk/two-way-merge-corner-case-fix:
  t1005: add test for "read-tree --reset -u A B"
  t1005: reindent
  unpack-trees: fix "read-tree -u --reset A B" with conflicted index

"git cat-file --batch-check=ok" did not check the existence of the
named object.

* sb/sha1-loose-object-info-check-existence:
  sha1_loose_object_info(): do not return success on missing object

"git diff -- ':(icase)makefile'" was unnecessarily rejected at the
command line parser.

* nd/magic-pathspec:
  diff: restrict pathspec limitations to diff b/f case only

Its value is the same as the number of entries in the "names"
string_list, so just use "names.nr" in its place.
Signed-off-by: NMichael Haggerty <mhagger@alum.mit.edu>
Acked-by: NStefan Beller <stefanbeller@googlemail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NJunio C Hamano <gitster@pobox.com>

The usage sample of add_submodule_odb() function in the Submodules
section expects non-zero return value for success, but the function
actually reports success with zero.
Helped-by: NRené Scharfe <l.s.r@web.de>
Reviewed-by: NHeiko Voigt <hvoigt@hvoigt.net>
Signed-off-by: NNick Townsend <nick.townsend@mac.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NJunio C Hamano <gitster@pobox.com>

When submodule.$name.update is given as hint from the upstream in
the .gitmodules file, we used to blindly copy it to .git/config,
unless there already is a value defined for the submodule.

However, there is no reason to expect that the update mode hinted by
the upstream is available in the version of Git the user is using,
and a really custom "!cmd" prepared by an upstream person running on
Linux may not even be available to a user on Windows.  It is simply
irresponsible to copy the setting blindly and to attempt to use it
during a later "submodule update" without validating it first.

Just show the suggested value to the diagnostic output, and set the
value to 'none' in the configuration, if it is not one of the ones
that are known to be supported by this version of Git.
Helped-by: NJens Lehmann <Jens.Lehmann@web.de>
Helped-by: NJeff King <peff@peff.net>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

git-cherry(1)'s "description" section has never really managed
to explain to me what the command does.  It contains too much
explanation of the algorithm instead of simply saying what
goals it achieves, and too much terminology that we otherwise
do not use (fork-point instead of merge-base).

Try a much more concise approach: state what it finds out, why
this is neat, and how the output is formatted, in a few short
paragraphs.  In return, provide much longer examples of how it
fits into a "format-patch | am" based workflow, and how it
compares to reading the same from git-log.

Also carefully avoid using "merge" in a context where it does
not mean something that comes from git-merge(1).  Instead, say
"apply" in an attempt to further link to patch workflow
concepts.

While there, also omit the language about _which_ upstream
branch we treat as the default.  I literally just learned that
we support having several, so let's not confuse new users
here, especially considering that git-config(1) does not
document this.

Prompted-by: a.huemer@commend.com on #git
Signed-off-by: NThomas Rast <tr@thomasrast.ch>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NJunio C Hamano <gitster@pobox.com>

* maint:
  remote-hg: don't decode UTF-8 paths into Unicode objects

The internal mercurial API expects ordinary 8-bit string objects, not
Unicode string objects.  With this change, the test-hg.sh unit tests
pass again.
Signed-off-by: NRichard Hansen <rhansen@bbn.com>
Reviewed-by: NFelipe Contreras <felipe.contreras@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NRene Scharfe <l.s.r@web.de>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Unbreaks a recent breakage due to use of unquote-c-style.

This may need to be cherry-picked down to 1.8.4.x series.

* 'rh/remote-hg-bzr-updates' (early part):
  remote-hg: don't decode UTF-8 paths into Unicode objects

"**" means bold in ASCIIDOC, so we need to escape it. This is similar
to 8447dc89 (gitignore.txt: fix documentation of "**" patterns -
2013-11-07)
Signed-off-by: NNguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Replace double quotes around literal examples with backticks
Signed-off-by: NJason St. John <jstjohn@purdue.edu>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

builtin_diff_b_f() needs a path, not pathspec. Other modes in diff
can deal with pathspec just fine. But because of the current
GUARD_PATHSPEC() location, other modes also reject :(glob) and
:(icase).

Move GUARD_PATHSPEC(), and the "path" assignment statement, which is
the reason of this GUARD_PATHSPEC(), inside builtin_diff_b_f().
Signed-off-by: NNguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NJunio C Hamano <gitster@pobox.com>

* mb/relnotes-1.8.5-fix:
  RelNotes: spelling & grammar fixes

Signed-off-by: NMarc Branchaud <marcnarc@xiplink.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>