Merge 'build-in git-mktree'

* commit '633e3556ccbc': (5835 commits)
  build-in git-mktree
  allow -t abbreviation for --track in git branch
  gitweb: Remove function prototypes (cleanup)
  Documentation: cloning to empty directory is allowed
  Clarify kind of conflict in merge-one-file helper
  git config: clarify --add and --get-color
  archive-tar.c: squelch a type mismatch warning
  Start 1.6.4 development
  Start 1.6.3.1 maintenance series.
  GIT 1.6.3
  t4029: use sh instead of bash
  t4200: convert sed expression which operates on non-text file to perl
  t4200: remove two unnecessary lines
  t/annotate-tests.sh: avoid passing a non-newline terminated file to sed
  t4118: avoid sed invocation on file without terminating newline
  t4118: add missing '&&'
  t8005: use egrep when extended regular expressions are required
  git-clean doc: the command only affects paths under $(cwd)
  improve error message in config.c
  t4018-diff-funcname: add cpp xfuncname pattern to syntax test
  ...

1 files changed, 34 insertions, 10 deletions

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index 9c83095693..7df3cef46f 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -13,9 +13,14 @@ DESCRIPTION
 -----------
 
 A `gitignore` file specifies intentionally untracked files that
-git should ignore.  Each line in a `gitignore` file specifies a
-pattern.
-
+git should ignore.
+Note that all the `gitignore` files really concern only files
+that are not already tracked by git;
+in order to ignore uncommitted changes in already tracked files,
+please refer to the 'git update-index --assume-unchanged'
+documentation.
+
+Each line in a `gitignore` file specifies a pattern.
 When deciding whether to ignore a path, git normally checks
 `gitignore` patterns from multiple sources, with the following
 order of precedence, from highest to lowest (within one level of
@@ -26,8 +31,8 @@ precedence, the last matching pattern decides the outcome):
 
  * Patterns read from a `.gitignore` file in the same directory
    as the path, or in any parent directory, with patterns in the
-   higher level files (up to the root) being overriden by those in
-   lower level files down to the directory containing the file.
+   higher level files (up to the toplevel of the work tree) being overridden
+   by those in lower level files down to the directory containing the file.
    These patterns match relative to the location of the
    `.gitignore` file.  A project normally includes such
    `.gitignore` files in its repository, containing patterns for
@@ -38,11 +43,23 @@ precedence, the last matching pattern decides the outcome):
  * Patterns read from the file specified by the configuration
    variable 'core.excludesfile'.
 
+Which file to place a pattern in depends on how the pattern is meant to
+be used. Patterns which should be version-controlled and distributed to
+other repositories via clone (i.e., files that all developers will want
+to ignore) should go into a `.gitignore` file. Patterns which are
+specific to a particular repository but which do not need to be shared
+with other related repositories (e.g., auxiliary files that live inside
+the repository but are specific to one user's workflow) should go into
+the `$GIT_DIR/info/exclude` file.  Patterns which a user wants git to
+ignore in all situations (e.g., backup or temporary files generated by
+the user's editor of choice) generally go into a file specified by
+`core.excludesfile` in the user's `~/.gitconfig`.
+
 The underlying git plumbing tools, such as
-gitlink:git-ls-files[1] and gitlink:git-read-tree[1], read
+'git-ls-files' and 'git-read-tree', read
 `gitignore` patterns specified by command-line options, or from
 files specified by command-line options.  Higher-level git
-tools, such as gitlink:git-status[1] and gitlink:git-add[1],
+tools, such as 'git-status' and 'git-add',
 use patterns from the sources specified above.
 
 Patterns have the following format:
@@ -57,6 +74,13 @@ Patterns have the following format:
    included again.  If a negated pattern matches, this will
    override lower precedence patterns sources.
 
+ - If the pattern ends with a slash, it is removed for the
+   purpose of the following description, but it would only find
+   a match with a directory.  In other words, `foo/` will match a
+   directory `foo` and paths underneath it, but will not match a
+   regular file or a symbolic link `foo` (this is consistent
+   with the way how pathspec works in general in git).
+
  - If the pattern does not contain a slash '/', git treats it as
    a shell glob pattern and checks for a match against the
    pathname without leading directories.
@@ -73,7 +97,7 @@ Patterns have the following format:
 An example:
 
 --------------------------------------------------------------
-    $ git-status
+    $ git status
     [...]
     # Untracked files:
     [...]
@@ -91,7 +115,7 @@ An example:
     *.html
     # except foo.html which is maintained by hand
     !foo.html
-    $ git-status
+    $ git status
     [...]
     # Untracked files:
     [...]
@@ -119,4 +143,4 @@ Frank Lichtenheld, and the git-list <git@vger.kernel.org>.
 
 GIT
 ---
-Part of the gitlink:git[7] suite
+Part of the linkgit:git[1] suite