21 files changed, 272 insertions, 71 deletions

diff --git a/Documentation/RelNotes/2.4.11.txt b/Documentation/RelNotes/2.4.11.txt
new file mode 100644
index 0000000000..723360295c
--- /dev/null
+++ b/Documentation/RelNotes/2.4.11.txt
@@ -0,0 +1,11 @@
+Git v2.4.11 Release Notes
+=========================
+
+Fixes since v2.4.10
+-------------------
+
+ * Bugfix patches were backported from the 'master' front to plug heap
+   corruption holes, to catch integer overflow in the computation of
+   pathname lengths, and to get rid of the name_path API.  Both of
+   these would have resulted in writing over an under-allocated buffer
+   when formulating pathnames while tree traversal.
diff --git a/Documentation/RelNotes/2.5.5.txt b/Documentation/RelNotes/2.5.5.txt
new file mode 100644
index 0000000000..37eae9a2d9
--- /dev/null
+++ b/Documentation/RelNotes/2.5.5.txt
@@ -0,0 +1,11 @@
+Git v2.5.5 Release Notes
+========================
+
+Fixes since v2.5.4
+------------------
+
+ * Bugfix patches were backported from the 'master' front to plug heap
+   corruption holes, to catch integer overflow in the computation of
+   pathname lengths, and to get rid of the name_path API.  Both of
+   these would have resulted in writing over an under-allocated buffer
+   when formulating pathnames while tree traversal.
diff --git a/Documentation/RelNotes/2.6.6.txt b/Documentation/RelNotes/2.6.6.txt
new file mode 100644
index 0000000000..023ad85ec6
--- /dev/null
+++ b/Documentation/RelNotes/2.6.6.txt
@@ -0,0 +1,11 @@
+Git v2.6.6 Release Notes
+========================
+
+Fixes since v2.6.5
+------------------
+
+ * Bugfix patches were backported from the 'master' front to plug heap
+   corruption holes, to catch integer overflow in the computation of
+   pathname lengths, and to get rid of the name_path API.  Both of
+   these would have resulted in writing over an under-allocated buffer
+   when formulating pathnames while tree traversal.
diff --git a/Documentation/RelNotes/2.7.3.txt b/Documentation/RelNotes/2.7.3.txt
new file mode 100644
index 0000000000..6adf038915
--- /dev/null
+++ b/Documentation/RelNotes/2.7.3.txt
@@ -0,0 +1,62 @@
+Git v2.7.3 Release Notes
+========================
+
+Fixes since v2.7.2
+------------------
+
+ * Traditionally, the tests that try commands that work on the
+   contents in the working tree were named with "worktree" in their
+   filenames, but with the recent addition of "git worktree"
+   subcommand, whose tests are also named similarly, it has become
+   harder to tell them apart.  The traditional tests have been renamed
+   to use "work-tree" instead in an attempt to differentiate them.
+
+ * Many codepaths forget to check return value from git_config_set();
+   the function is made to die() to make sure we do not proceed when
+   setting a configuration variable failed.
+
+ * Handling of errors while writing into our internal asynchronous
+   process has been made more robust, which reduces flakiness in our
+   tests.
+
+ * "git show 'HEAD:Foo[BAR]Baz'" did not interpret the argument as a
+   rev, i.e. the object named by the the pathname with wildcard
+   characters in a tree object.
+
+ * "git rev-parse --git-common-dir" used in the worktree feature
+   misbehaved when run from a subdirectory.
+
+ * The "v(iew)" subcommand of the interactive "git am -i" command was
+   broken in 2.6.0 timeframe when the command was rewritten in C.
+
+ * "git merge-tree" used to mishandle "both sides added" conflict with
+   its own "create a fake ancestor file that has the common parts of
+   what both sides have added and do a 3-way merge" logic; this has
+   been updated to use the usual "3-way merge with an empty blob as
+   the fake common ancestor file" approach used in the rest of the
+   system.
+
+ * The memory ownership rule of fill_textconv() API, which was a bit
+   tricky, has been documented a bit better.
+
+ * The documentation did not clearly state that the 'simple' mode is
+   now the default for "git push" when push.default configuration is
+   not set.
+
+ * Recent versions of GNU grep are pickier when their input contains
+   arbitrary binary data, which some of our tests uses.  Rewrite the
+   tests to sidestep the problem.
+
+ * A helper function "git submodule" uses since v2.7.0 to list the
+   modules that match the pathspec argument given to its subcommands
+   (e.g. "submodule add <repo> <path>") has been fixed.
+
+ * "git config section.var value" to set a value in per-repository
+   configuration file failed when it was run outside any repository,
+   but didn't say the reason correctly.
+
+ * The code to read the pack data using the offsets stored in the pack
+   idx file has been made more carefully check the validity of the
+   data in the idx.
+
+Also includes documentation and test updates.
diff --git a/Documentation/RelNotes/2.7.4.txt b/Documentation/RelNotes/2.7.4.txt
new file mode 100644
index 0000000000..883ae896fe
--- /dev/null
+++ b/Documentation/RelNotes/2.7.4.txt
@@ -0,0 +1,11 @@
+Git v2.7.4 Release Notes
+========================
+
+Fixes since v2.7.3
+------------------
+
+ * Bugfix patches were backported from the 'master' front to plug heap
+   corruption holes, to catch integer overflow in the computation of
+   pathname lengths, and to get rid of the name_path API.  Both of
+   these would have resulted in writing over an under-allocated buffer
+   when formulating pathnames while tree traversal.
diff --git a/Documentation/RelNotes/2.8.0.txt b/Documentation/RelNotes/2.8.0.txt
index b7a6d6826d..25079710fa 100644
--- a/Documentation/RelNotes/2.8.0.txt
+++ b/Documentation/RelNotes/2.8.0.txt
@@ -16,7 +16,9 @@ UI, Workflows & Features
    the source repository has packed references for a long time, and
    nobody noticed nor complained about it.
 
- * "branch --delete" has "branch -d" but "push --delete" does not.
+ * "push" learned that its "--delete" option can be shortened to
+   "-d", just like "branch --delete" and "branch -d" are the same
+   thing.
 
  * "git blame" learned to produce the progress eye-candy when it takes
    too much time before emitting the first line of the result.
@@ -32,7 +34,7 @@ UI, Workflows & Features
    have a place to store the updated notes tree, iow, a ref).
 
  * "git grep" by default does not fall back to its "--no-index"
-   behaviour outside a directory under Git's control (otherwise the
+   behavior outside a directory under Git's control (otherwise the
    user may by mistake end up running a huge recursive search); with a
    new configuration (set in $HOME/.gitconfig--by definition this
    cannot be set in the config file per project), this safety can be
@@ -53,7 +55,7 @@ UI, Workflows & Features
 
  * Many commands that read files that are expected to contain text
    that is generated (or can be edited) by the end user to control
-   their behaviour (e.g. "git grep -f <filename>") have been updated
+   their behavior (e.g. "git grep -f <filename>") have been updated
    to be more tolerant to lines that are terminated with CRLF (they
    used to treat such a line to contain payload that ends with CR,
    which is usually not what the users expect).
@@ -131,8 +133,8 @@ UI, Workflows & Features
 
  * Across the transition at around Git version 2.0, the user used to
    get a pretty loud warning when running "git push" without setting
-   push.default configuration variable.  We no longer warn, given that
-   the transition is over long time ago.
+   push.default configuration variable.  We no longer warn because the
+   transition was completed a long time ago.
 
  * README has been renamed to README.md and its contents got tweaked
    slightly to make it easier on the eyes.
@@ -143,8 +145,8 @@ Performance, Internal Implementation, Development Support etc.
  * Add a framework to spawn a group of processes in parallel, and use
    it to run "git fetch --recurse-submodules" in parallel.
 
- * A slight update to the Makefile to mark "phoney" targets
-   as such correctly.
+ * A slight update to the Makefile to mark ".PHONY" targets as such
+   correctly.
 
  * In-core storage of the reverse index for .pack files (which lets
    you go from a pack offset to an object name) has been streamlined.
@@ -185,16 +187,10 @@ Performance, Internal Implementation, Development Support etc.
    with expectations that are not satisfiable on Git for Windows.
 
  * Some calls to strcpy(3) triggers a false warning from static
-   analysers that are less intelligent than humans, and reducing the
+   analyzers that are less intelligent than humans, and reducing the
    number of these false hits helps us notice real issues.  A few
-   calls to strcpy(3) in test-path-utils that are already safe has
-   been rewritten to avoid false wanings.
-
- * Some calls to strcpy(3) triggers a false warning from static
-   analysers that are less intelligent than humans, and reducing the
-   number of these false hits helps us notice real issues.  A few
-   calls to strcpy(3) in "git rerere" that are already safe has been
-   rewritten to avoid false wanings.
+   calls to strcpy(3) in a couple of protrams that are already safe
+   has been rewritten to avoid false warnings.
 
  * The "name_path" API was an attempt to reduce the need to construct
    the full path out of a series of path components while walking a
@@ -240,6 +236,23 @@ Performance, Internal Implementation, Development Support etc.
  * Out of maintenance gcc on OSX 10.6 fails to compile the code in
    'master'; work it around by using clang by default on the platform.
 
+ * The "name_path" API was an attempt to reduce the need to construct
+   the full path out of a series of path components while walking a
+   tree hierarchy, but over time made less efficient because the path
+   needs to be flattened, e.g. to be compared with another path that
+   is already flat, in many cases.  The API has been removed and its
+   users have been rewritten to simplify the overall code complexity.
+   This incidentally also closes some heap-corruption holes.
+
+ * Recent versions of GNU grep is pickier than before to decide if a
+   file is "binary" and refuse to give line-oriented hits when we
+   expect it to, unless explicitly told with "-a" option.  As our
+   scripted Porcelains use sane_grep wrapper for line-oriented data,
+   even when the line may contain non-ASCII payload we took from
+   end-user data, use "grep -a" to implement sane_grep wrapper when
+   using an implementation of "grep" that takes the "-a" option.
+
+
 
 Also contains various documentation updates and code clean-ups.
 
@@ -268,7 +281,7 @@ notes for details).
  * "git send-email" was confused by escaped quotes stored in the alias
    files saved by "mutt", which has been corrected.
 
- * A few unportable C construct have been spotted by clang compiler
+ * A few non-portable C construct have been spotted by clang compiler
    and have been fixed.
 
  * The documentation has been updated to hint the connection between
@@ -329,17 +342,17 @@ notes for details).
  * dirname() emulation has been added, as Msys2 lacks it.
 
  * The underlying machinery used by "ls-files -o" and other commands
-   have been taught not to create empty submodule ref cache for a
+   has been taught not to create empty submodule ref cache for a
    directory that is not a submodule.  This removes a ton of wasted
    CPU cycles.
 
  * "git worktree" had a broken code that attempted to auto-fix
    possible inconsistency that results from end-users moving a
    worktree to different places without telling Git (the original
-   repository needs to maintain backpointers to its worktrees, but
-   "mv" run by end-users who are not familiar with that fact will
-   obviously not adjust them), which actually made things worse
-   when triggered.
+   repository needs to maintain back-pointers to its worktrees,
+   but "mv" run by end-users who are not familiar with that fact
+   will obviously not adjust them), which actually made things
+   worse when triggered.
 
  * The low-level merge machinery has been taught to use CRLF line
    termination when inserting conflict markers to merged contents that
@@ -372,10 +385,6 @@ notes for details).
    misbehaved when run from a subdirectory.
    (merge 17f1365 nd/git-common-dir-fix later to maint).
 
- * Another try to add support to the ignore mechanism that lets you
-   say "this is excluded" and then later say "oh, no, this part (that
-   is a subset of the previous part) is not excluded".
-
  * "git worktree add -B <branchname>" did not work.
 
  * The "v(iew)" subcommand of the interactive "git am -i" command was
diff --git a/Documentation/RelNotes/2.8.1.txt b/Documentation/RelNotes/2.8.1.txt
new file mode 100644
index 0000000000..ef6d80b008
--- /dev/null
+++ b/Documentation/RelNotes/2.8.1.txt
@@ -0,0 +1,9 @@
+Git v2.8.1 Release Notes
+========================
+
+Fixes since v2.8
+----------------
+
+ * "make rpmbuild" target was broken as its input, git.spec.in, was
+   not updated to match a file it describes that has been renamed
+   recently.  This has been fixed.
diff --git a/Documentation/RelNotes/2.8.2.txt b/Documentation/RelNotes/2.8.2.txt
new file mode 100644
index 0000000000..3e1f0bb31b
--- /dev/null
+++ b/Documentation/RelNotes/2.8.2.txt
@@ -0,0 +1,17 @@
+Git v2.8.2 Release Notes
+========================
+
+Fixes since v2.8.1
+------------------
+
+ * The embedded args argv-array in the child process is used to build
+   the command line to run pack-objects instead of using a separate
+   array of strings.
+
+ * Bunch of tests on "git clone" has been renumbered for better
+   organization.
+
+ * The tests that involve running httpd leaked the system-wide
+   configuration in /etc/gitconfig to the tested environment.
+
+Also contains minor documentation updates and code clean-ups.
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 306b7e3604..32f48ed647 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -286,8 +286,8 @@ endif::git-format-patch[]
 
 ifndef::git-format-patch[]
 --check::
-	Warn if changes introduce whitespace errors.  What are
-	considered whitespace errors is controlled by `core.whitespace`
+	Warn if changes introduce conflict markers or whitespace errors.
+	What are considered whitespace errors is controlled by `core.whitespace`
 	configuration.  By default, trailing whitespaces (including
 	lines that solely consist of whitespaces) and a space character
 	that is immediately followed by a tab character inside the
diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index d9ed6a1a4e..8ddb207409 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -13,7 +13,7 @@ SYNOPSIS
 	  [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse]
 	  [--allow-binary-replacement | --binary] [--reject] [-z]
 	  [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached]
-	  [--ignore-space-change | --ignore-whitespace ]
+	  [--ignore-space-change | --ignore-whitespace]
 	  [--whitespace=(nowarn|warn|fix|error|error-all)]
 	  [--exclude=<path>] [--include=<path>] [--directory=<root>]
 	  [--verbose] [--unsafe-paths] [<patch>...]
@@ -21,6 +21,8 @@ SYNOPSIS
 DESCRIPTION
 -----------
 Reads the supplied diff output (i.e. "a patch") and applies it to files.
+When running from a subdirectory in a repository, patched paths
+outside the directory are ignored.
 With the `--index` option the patch is also applied to the index, and
 with the `--cached` option the patch is only applied to the index.
 Without these options, the command applies the patch only to files,
diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt
index f60ee051f8..e94367a5ed 100644
--- a/Documentation/git-check-ignore.txt
+++ b/Documentation/git-check-ignore.txt
@@ -114,7 +114,6 @@ SEE ALSO
 linkgit:gitignore[5]
 linkgit:gitconfig[5]
 linkgit:git-ls-files[1]
-GIT_TRACE_EXCLUDE in linkgit:git[1]
 
 GIT
 ---
diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index 153b2d89b5..6fc08e3d89 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -58,13 +58,13 @@ that location (you can say '--local' but that is the default).
 This command will fail with non-zero status upon error.  Some exit
 codes are:
 
-. The config file is invalid (ret=3),
-. can not write to the config file (ret=4),
-. no section or name was provided (ret=2),
-. the section or key is invalid (ret=1),
-. you try to unset an option which does not exist (ret=5),
-. you try to unset/set an option for which multiple lines match (ret=5), or
-. you try to use an invalid regexp (ret=6).
+- The config file is invalid (ret=3),
+- can not write to the config file (ret=4),
+- no section or name was provided (ret=2),
+- the section or key is invalid (ret=1),
+- you try to unset an option which does not exist (ret=5),
+- you try to unset/set an option for which multiple lines match (ret=5), or
+- you try to use an invalid regexp (ret=6).
 
 On success, the command returns the exit code 0.
 
@@ -86,8 +86,7 @@ OPTIONS
 	found and the last value if multiple key values were found.
 
 --get-all::
-	Like get, but does not fail if the number of values for the key
-	is not exactly one.
+	Like get, but returns all values for a multi-valued key.
 
 --get-regexp::
 	Like --get-all, but interprets the name as a regular expression and
@@ -102,7 +101,7 @@ OPTIONS
 	given URL is returned (if no such key exists, the value for
 	section.key is used as a fallback).  When given just the
 	section as name, do so for all the keys in the section and
-	list them.
+	list them.  Returns error code 1 if no value is found.
 
 --global::
 	For writing options: write to global `~/.gitconfig` file
diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt
index 8680f45f8d..239623cc24 100644
--- a/Documentation/git-fetch-pack.txt
+++ b/Documentation/git-fetch-pack.txt
@@ -104,6 +104,10 @@ be in a separate packet, and the list must end with a flush packet.
 	The remote heads to update from. This is relative to
 	$GIT_DIR (e.g. "HEAD", "refs/heads/master").  When
 	unspecified, update from all heads the remote side has.
++
+If the remote has enabled the options `uploadpack.allowTipSHA1InWant` or
+`uploadpack.allowReachableSHA1InWant`, they may alternatively be 40-hex
+sha1s present on the remote.
 
 SEE ALSO
 --------
diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt
index 738cfde10c..35e3170918 100644
--- a/Documentation/git-p4.txt
+++ b/Documentation/git-p4.txt
@@ -515,20 +515,18 @@ git-p4.pathEncoding::
 	Git expects paths encoded as UTF-8. Use this config to tell git-p4
 	what encoding Perforce had used for the paths. This encoding is used
 	to transcode the paths to UTF-8. As an example, Perforce on Windows
-	often uses “cp1252” to encode path names.
+	often uses "cp1252" to encode path names.
 
 git-p4.largeFileSystem::
 	Specify the system that is used for large (binary) files. Please note
 	that large file systems do not support the 'git p4 submit' command.
-	Only Git LFS [1] is implemented right now. Download
-	and install the Git LFS command line extension to use this option
-	and configure it like this:
+	Only Git LFS is implemented right now (see https://git-lfs.github.com/
+	for more information). Download and install the Git LFS command line
+	extension to use this option and configure it like this:
 +
 -------------
 git config       git-p4.largeFileSystem GitLFS
 -------------
-+
-	[1] https://git-lfs.github.com/
 
 git-p4.largeFileExtensions::
 	All files matching a file extension in the list will be processed
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 6cca8bb51d..6ed610a031 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -3,7 +3,7 @@ git-rebase(1)
 
 NAME
 ----
-git-rebase - Forward-port local commits to the updated upstream head
+git-rebase - Reapply commits on top of another base tip
 
 SYNOPSIS
 --------
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 0c0f60b20e..fb23a98a17 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -1034,6 +1034,8 @@ listed below are allowed:
 	url = http://server.org/svn
 	fetch = trunk/project-a:refs/remotes/project-a/trunk
 	branches = branches/*/project-a:refs/remotes/project-a/branches/*
+	branches = branches/release_*:refs/remotes/project-a/branches/release_*
+	branches = branches/re*se:refs/remotes/project-a/branches/*
 	tags = tags/*/project-a:refs/remotes/project-a/tags/*
 ------------------------------------------------------------------------
 
@@ -1044,6 +1046,16 @@ independent path component (surrounded by '/' or EOL).   This
 type of configuration is not automatically created by 'init' and
 should be manually entered with a text-editor or using 'git config'.
 
+Also note that only one asterisk is allowed per word. For example:
+
+	branches = branches/re*se:refs/remotes/project-a/branches/*
+
+will match branches 'release', 'rese', 're123se', however
+
+	branches = branches/re*s*e:refs/remotes/project-a/branches/*
+
+will produce an error.
+
 It is also possible to fetch a subset of branches or tags by using a
 comma-separated list of names within braces. For example:
 
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 2754af8f77..8afe349781 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -43,16 +43,24 @@ unreleased) version of Git, that is available from the 'master'
 branch of the `git.git` repository.
 Documentation for older releases are available here:
 
-* link:v2.7.2/git.html[documentation for release 2.7.2]
+* link:v2.8.1/git.html[documentation for release 2.8.1]
 
 * release notes for
+  link:RelNotes/2.8.1.txt[2.8.1].
+  link:RelNotes/2.8.0.txt[2.8].
+
+* link:v2.7.3/git.html[documentation for release 2.7.3]
+
+* release notes for
+  link:RelNotes/2.7.3.txt[2.7.3],
   link:RelNotes/2.7.2.txt[2.7.2],
   link:RelNotes/2.7.1.txt[2.7.1],
   link:RelNotes/2.7.0.txt[2.7].
 
-* link:v2.6.5/git.html[documentation for release 2.6.5]
+* link:v2.6.6/git.html[documentation for release 2.6.6]
 
 * release notes for
+  link:RelNotes/2.6.6.txt[2.6.6],
   link:RelNotes/2.6.5.txt[2.6.5],
   link:RelNotes/2.6.4.txt[2.6.4],
   link:RelNotes/2.6.3.txt[2.6.3],
@@ -60,18 +68,20 @@ Documentation for older releases are available here:
   link:RelNotes/2.6.1.txt[2.6.1],
   link:RelNotes/2.6.0.txt[2.6].
 
-* link:v2.5.4/git.html[documentation for release 2.5.4]
+* link:v2.5.5/git.html[documentation for release 2.5.5]
 
 * release notes for
+  link:RelNotes/2.5.5.txt[2.5.5],
   link:RelNotes/2.5.4.txt[2.5.4],
   link:RelNotes/2.5.3.txt[2.5.3],
   link:RelNotes/2.5.2.txt[2.5.2],
   link:RelNotes/2.5.1.txt[2.5.1],
   link:RelNotes/2.5.0.txt[2.5].
 
-* link:v2.4.10/git.html[documentation for release 2.4.10]
+* link:v2.4.11/git.html[documentation for release 2.4.11]
 
 * release notes for
+  link:RelNotes/2.4.11.txt[2.4.11],
   link:RelNotes/2.4.10.txt[2.4.10],
   link:RelNotes/2.4.9.txt[2.4.9],
   link:RelNotes/2.4.8.txt[2.4.8],
@@ -1065,11 +1075,6 @@ of clones and fetches.
 	cloning of shallow repositories.
 	See 'GIT_TRACE' for available trace output options.
 
-'GIT_TRACE_EXCLUDE'::
-	Enables trace messages that can help debugging .gitignore
-	processing. See 'GIT_TRACE' for available trace output
-	options.
-
 'GIT_LITERAL_PATHSPECS'::
 	Setting this variable to `1` will cause Git to treat all
 	pathspecs literally, rather than as glob patterns. For example,
@@ -1128,7 +1133,7 @@ of clones and fetches.
 	    connection (or proxy, if configured)
 
 	  - `ssh`: git over ssh (including `host:path` syntax,
-	    `git+ssh://`, etc).
+	    `ssh://`, etc).
 
 	  - `http`: git over http, both "smart http" and "dumb http".
 	    Note that this does _not_ include `https`; if you want both,
diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index 7ba0ac965d..a2f59b194c 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -397,7 +397,7 @@ preceding SP is also omitted.  Currently, no commands pass any
 'extra-info'.
 
 The hook always runs after the automatic note copying (see
-"notes.rewrite.<command>" in linkgit:git-config.txt[1]) has happened, and
+"notes.rewrite.<command>" in linkgit:git-config[1]) has happened, and
 thus has access to these notes.
 
 The following command-specific comments apply:
diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index 3ded6fdc99..473623d631 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -82,12 +82,12 @@ PATTERN FORMAT
 
  - An optional prefix "`!`" which negates the pattern; any
    matching file excluded by a previous pattern will become
-   included again.
+   included again. It is not possible to re-include a file if a parent
+   directory of that file is excluded. Git doesn't list excluded
+   directories for performance reasons, so any patterns on contained
+   files have no effect, no matter where they are defined.
    Put a backslash ("`\`") in front of the first "`!`" for patterns
    that begin with a literal "`!`", for example, "`\!important!.txt`".
-   It is possible to re-include a file if a parent directory of that
-   file is excluded if certain conditions are met. See section NOTES
-   for detail.
 
  - If the pattern ends with a slash, it is removed for the
    purpose of the following description, but it would only find
@@ -141,15 +141,6 @@ not tracked by Git remain untracked.
 To stop tracking a file that is currently tracked, use
 'git rm --cached'.
 
-To re-include files or directories when their parent directory is
-excluded, the following conditions must be met:
-
- - The rules to exclude a directory and re-include a subset back must
-   be in the same .gitignore file.
-
- - The directory part in the re-include rules must be literal (i.e. no
-   wildcards)
-
 EXAMPLES
 --------
 
diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt
index 5f0757dcc9..695bd4bf43 100644
--- a/Documentation/technical/api-parse-options.txt
+++ b/Documentation/technical/api-parse-options.txt
@@ -231,6 +231,13 @@ There are some macros to easily define options:
 	pass the command-line option, which can be specified multiple times,
 	to another command.
 
+`OPT_CMDMODE(short, long, &int_var, description, enum_val)`::
+	Define an "operation mode" option, only one of which in the same
+	group of "operating mode" options that share the same `int_var`
+	can be given by the user. `enum_val` is set to `int_var` when the
+	option is used, but an error is reported if other "operating mode"
+	option has already set its value to the same `int_var`.
+
 
 The last element of the array must be `OPT_END()`.
 
diff --git a/Documentation/technical/api-trace.txt b/Documentation/technical/api-trace.txt
index 097a651d96..389ae16d15 100644
--- a/Documentation/technical/api-trace.txt
+++ b/Documentation/technical/api-trace.txt
@@ -95,3 +95,46 @@ for (;;) {
 }
 trace_performance(t, "frotz");
 ------------
+
+Bugs & Caveats
+--------------
+
+GIT_TRACE_* environment variables can be used to tell Git to show
+trace output to its standard error stream. Git can often spawn a pager
+internally to run its subcommand and send its standard output and
+standard error to it.
+
+Because GIT_TRACE_PERFORMANCE trace is generated only at the very end
+of the program with atexit(), which happens after the pager exits, it
+would not work well if you send its log to the standard error output
+and let Git spawn the pager at the same time.
+
+As a work around, you can for example use '--no-pager', or set
+GIT_TRACE_PERFORMANCE to another file descriptor which is redirected
+to stderr, or set GIT_TRACE_PERFORMANCE to a file specified by its
+absolute path.
+
+For example instead of the following command which by default may not
+print any performance information:
+
+------------
+GIT_TRACE_PERFORMANCE=2 git log -1
+------------
+
+you may want to use:
+
+------------
+GIT_TRACE_PERFORMANCE=2 git --no-pager log -1
+------------
+
+or:
+
+------------
+GIT_TRACE_PERFORMANCE=3 3>&2 git log -1
+------------
+
+or:
+
+------------
+GIT_TRACE_PERFORMANCE=/path/to/log/file git log -1
+------------