Document the dirconfig format more precisely

The parser docstring only described + and - prefixes even though the
function returns a 3-tuple including the ! ensure bucket. Fill that
in, and pull the path-vs-glob distinction out of the prose in
projects.adoc into a subsection of its own — that ambiguity is at
the root of recurring confusion (#740, #1109, #680, #1941).

2 files changed, 42 insertions, 11 deletions

diff --git a/doc/modules/ROOT/pages/projects.adoc b/doc/modules/ROOT/pages/projects.adoc
index 16b38f8..f1f4a5f 100644
--- a/doc/modules/ROOT/pages/projects.adoc
+++ b/doc/modules/ROOT/pages/projects.adoc
@@ -866,11 +866,35 @@ When a path is overridden, its contents are still subject to ignore
 patterns. To override those files as well, specify their full path
 with a bang prefix.
 
+==== Path entries vs. glob patterns
+
+The two ignore examples above look similar but go through different
+matchers. An entry that begins with a slash (e.g. `-/log`,
+`+/src/foo`, `!/src/foo`) is treated as a *path* relative to the
+project root and is expanded literally. An entry without a leading
+slash (e.g. `-tmp`, `-*.rb`) is treated as a *glob pattern* applied
+to every file's path. As a consequence:
+
+* `-/log` ignores only the top-level `log` directory.
+* `-log` ignores anything called `log` at any depth, but only matches
+  full path components — it will not match `xlog` or `log.txt`.
+* `-*.rb` ignores any file whose path matches the glob `*.rb`.
+
+If a glob pattern doesn't behave the way you'd expect — particularly
+across nested directories — try the explicit path form first to
+confirm whether the file is being indexed at all.
+
+==== Comments
+
 If you would like to include comment lines in your .projectile file,
 you can customize the variable `projectile-dirconfig-comment-prefix`.
 Assigning it a non-nil character value, e.g. `#`, will cause lines in
-the `.projectile` file starting with that character to be treated as
-comments instead of patterns.
+the `.projectile` file whose first non-whitespace character matches
+that character to be treated as comments instead of patterns.
+
+The same is true of the `+`, `-`, and `!` prefixes: leading spaces
+and tabs before the prefix are skipped, so accidental indentation
+won't silently turn the entry into a literal ignore pattern.
 
 === Ignored files using the project indexing tools
 
diff --git a/projectile.el b/projectile.el
index 2d87bb3..f0ec260 100644
--- a/projectile.el
+++ b/projectile.el
@@ -2196,15 +2196,22 @@ Returns a list of (KEEP IGNORE ENSURE) or nil if the file doesn't exist."
 (defun projectile-parse-dirconfig-file ()
   "Parse project ignore file and return directories to ignore and keep.
 
-The return value will be a list of three elements, the car being
-the list of directories to keep, the cadr being the list of files
-or directories to ignore, and the caddr being the list of files
-or directories to ensure.
-
-Strings starting with + will be added to the list of directories
-to keep, and strings starting with - will be added to the list of
-directories to ignore.  For backward compatibility, without a
-prefix the string will be assumed to be an ignore string.
+The return value is a list of three elements: the car is the list
+of directories to keep, the cadr is the list of files or
+directories to ignore, and the caddr is the list of files or
+directories to ensure (i.e. forcibly include even when otherwise
+ignored).
+
+Lines are dispatched on their first non-whitespace character:
+
+  +  add to the keep list
+  -  add to the ignore list
+  !  add to the ensure list
+
+Without a prefix, the line is assumed to be an ignore pattern, for
+backward compatibility.  When `projectile-dirconfig-comment-prefix'
+is non-nil, lines whose first non-whitespace character matches it
+are treated as comments.
 
 Results are cached per project root and invalidated when the
 dirconfig file's modification time changes."