Merge branch 'jc/apply-3way'

"git apply" learned to wiggle the base version and perform three-way
merge when a patch does not exactly apply to the version you have.

* jc/apply-3way:
  apply: tests for the --3way option
  apply: document --3way option
  apply: allow rerere() to work on --3way results
  apply: register conflicted stages to the index
  apply: --3way with add/add conflict
  apply: move verify_index_match() higher
  apply: plug the three-way merge logic in
  apply: fall back on three-way merge
  apply: accept -3/--3way command line option
  apply: move "already exists" logic to check_to_create()
  apply: move check_to_create_blob() closer to its sole caller
  apply: further split load_preimage()
  apply: refactor "previous patch" logic
  apply: split load_preimage() helper function out
  apply: factor out checkout_target() helper function
  apply: refactor read_file_or_gitlink()
  apply: clear_image() clears things a bit more
  apply: a bit more comments on PATH_TO_BE_DELETED
  apply: fix an incomplete comment in check_patch()

Documentation/git-apply.txt

@@ -9,7 +9,7 @@ git-apply - Apply a patch to files and/or to the index
 SYNOPSIS
 --------
 [verse]
-'git apply' [--stat] [--numstat] [--summary] [--check] [--index]
+'git apply' [--stat] [--numstat] [--summary] [--check] [--index] [--3way]
 	  [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse]
 	  [--allow-binary-replacement | --binary] [--reject] [-z]
 	  [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached]
@@ -72,6 +72,15 @@ OPTIONS
 	cached data, apply the patch, and store the result in the index
 	without using the working tree. This implies `--index`.
 
+-3::
+--3way::
+	When the patch does not apply cleanly, fall back on 3-way merge if
+	the patch records the identity of blobs it is supposed to apply to,
+	and we have those blobs available locally, possibly leaving the
+	conflict markers in the files in the working tree for the user to
+	resolve.  This option implies the `--index` option, and is incompatible
+	with the `--reject` and the `--cached` options.
+
 --build-fake-ancestor=<file>::
 	Newer 'git diff' output has embedded 'index information'
 	for each blob to help identify the original version that