early if the key is unknown

accept hostkeys for git repos and prevent task hangs when the key is unknown

This adds two parameters to the git module:

  bare (boolean)
    Indicates this is to be a bare repositori

  reference (string)
    Indicates the path or url to the reference repo.
    Check out the "--reference" option in the "git clone"
    man page

Added appropriate tests.

The return values from check mode and non-check mode should match in all cases,
except when a SHA-1 hash is used as version, as there is no way to check if it
is a valid hash using `git ls-remote`.

Also, to accomodate this change, the force flag for the reset function has been
removed so that we can do the checking in main.

This allows the module to return the before/after revisions in all cases.

The functions either return rc=0 or call fail_json themselves.

This removes ambiguity at the expense of slight backward incompatibility.

Fixed so that we no longer check with the remote if a checkout already is at the desired sha version.

This disclaimer already exists in library/source_control/hg but not here.  It affects both and was discussed awhile back on: https://groups.google.com/forum/#!msg/ansible-project/q9G9xIdsRxo/XJhQzuS-qSoJ  However no PR was ever sent to fix the doc.

"UnboundLocalError: local variable 'branch' referenced before assignment" is
raised in git, line 282, in switch_version.

Exception is raised when version is not branch and version checkout fails.
E.g. when version is nonexistant commit.

Git is unable to checkout the specified `version` when the repository is
cloned with a reduced history (`depth`).  However, if the repository is
already cloned, subsequent git module calls will update the repository
(default update=True), then properly checkout the specified `version`.
To allow the initial call to properly clone the specified `version`, at
the specified `depth`, this patch adds the `--branch` parameter when
cloning the repository.

This does two things:
* add --recursive option to git clone command in clone().  This will
  initialize all submodules when cloning a remote repository.
* Add submodule_update() and call that from fetch().  submodule_update()
  calls two git commands iff the file .gitmodules exists in the
  repository:
  * 'git submodule sync' - synchronizes the submodules' remote URL
    configuration setting to the value in .gitmodules.
  * 'git submodule update --init --recursive' - initialize and update
    registered submodules to the commit specified in the index of the
    containing repository.

If a repository was cloned without --recursive, submodule_update() will
ensure that the submodules are initialized and updated.

  Migrated all examples: in DOCUMENTATION=''' string to standalone EXAMPLES=''' string
  Added deprecation warning to moduledev.rst and remove deprecated example from it
  Fixed up a few typos and uppercased some acronyms.
  add consistency to how EXAMPLES are formatted

remove unused git function is_current_branch (looks like it returns always True anyway which might be wrong)

This will allow just making sure the repo exists w/out actually making
any chnages to it. Useful if you're going to run a play repeatedly
against a host that might have active development going on in the
repository (think initial bootstrap of a developers system, and
continued playbook runs to work on other projects).

See issue #2471

This fixes get_remote_head() to be smarter about how to check remote
head.  It checks if it is a remote branch or tag and then checks for the
remote object id associated with it.  If it is sha1, get_remote_head()
returns it as-is since there doesn't appear to be a way to check a
remote repository for a specific object/sha1.  is_remote_tag() is added
to help out the new functionalit in get_remote_head().

In main(), if check_mode is true and version is a sha1, the module now
checks to see if the object is present.

Related to issue #2114.  This hooks in check_mode to git module.  This
will exit with changed=True at the following places:

* If the repo has not been cloned
* If the destination has local modifications, this will exit with
  changed=True.  This is because reset() will exit anyways if there are
  local mods and force is False.
* If the remote HEAD commit id is not the same as that of the local HEAD.
  This is determined by get_remote_head() that runs 'git ls-remote' to
  determine remote HEAD.

Lastly, if this is run with check_mode enabled, this will exit with
changed=False before fetch() is invoked so that no local mods are made.

Both modules seboolean and zfs have not been adapted since they defer from the default (either by having a 'null' or special state, or prefering "on"/"off" for state indication.