[PATCH] make slash-rules more readable

["Dr. Adam Nielsen" <admin@in-ici.net>]

---
 Documentation/gitignore.txt | 37 ++++++++++++++++++++++++-------------
 1 file changed, 24 insertions(+), 13 deletions(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index b5bc9dbff0..3a6fb9117c 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -89,24 +89,35 @@ PATTERN FORMAT
    Put a backslash ("`\`") in front of the first "`!`" for patterns
    that begin with a literal "`!`", for example, "`\!important!.txt`".
 
- - If the pattern ends with a slash, it is removed for the
-   purpose of the following description, but it would only find
+ - If the pattern ends with a slash, 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 relative to the location of the `.gitignore` file
-   (relative to the toplevel of the work tree if not from a
-   `.gitignore` file).
-
- - Otherwise, Git treats the pattern as a shell glob: "`*`" matches
-   anything except "`/`", "`?`" matches any one character except "`/`"
-   and "`[]`" matches one character in a selected range. See
-   fnmatch(3) and the FNM_PATHNAME flag for a more detailed
-   description.
+ - If the pattern contains no slash "`/`" (except an optional trailing slash),
+   the pattern is matched against all files and folders (recursively)
+   from the location of the `.gitignore` file.
+   For example, `frotz/` matches `frotz` and `a/frotz` that
+   is a directory (relative from the `.gitignore` file). 
+
+ - A pattern that contains a non-trailing slash is matched relative to the 
+   location of the `.gitignore` file.
+   For example, `doc/frotz/` matches `doc/frotz` directory, but not 
+   `a/doc/frotz` (relative from the `.gitignore` file). 
+   Note that the pattern `doc/frotz` and `/doc/frotz`  
+   have the same effect in any `.gitignore` file, while `/bar` and `bar` 
+   have not the same effect (`/bar` will not match `foo/bar`).
+
+ - An asterisk "`*`" matches anything except a slash.  A
+   pattern "foo/*", for example, matches "foo/test.json" (a
+   regular file), "foo/bar" (a diretory), but it does not match
+   "foo/bar/hello.c" (a regular file), as the asterisk in the
+   patter does not match "bar/hello.c" which has a slash in it.
+   The character "`?`" matches any one character except "`/`"
+   The range notation, e.g. `[a-zA-Z]`, can be used to match
+   one of the characters in a range. See fnmatch(3) and the 
+   FNM_PATHNAME flag for a more detailed description.
 
  - A leading slash matches the beginning of the pathname.
    For example, "/{asterisk}.c" matches "cat-file.c" but not
-- 
2.17.1