git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / Atom feed
From: "Dr. Adam Nielsen" <admin@in-ici.net>
To: git@vger.kernel.org
Cc: "Dr. Adam Nielsen" <admin@in-ici.net>
Subject: [PATCH] make slash-rules more readable
Date: Sun,  2 Jun 2019 11:04:15 +0200
Message-ID: <20190602090415.5889-1-admin@in-ici.net> (raw)

gitignore.txt: make slash-rules more readable

Remove meta-rule in a paragraph for trailing-slash.
Be precise whenever a trailing slash would make a 
difference. Improve or add paragraphs relevant 
for pattern with slash. Add some slash examples 
in example section.

Signed-off-by: Dr. Adam Nielsen <admin@in-ici.net>

---
 Documentation/gitignore.txt | 69 ++++++++++++++++++++++++++-----------
 1 file changed, 48 insertions(+), 21 deletions(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index b5bc9dbff0..46195649f1 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -89,28 +89,39 @@ 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
+ - A slash `/` is used as a directory separator. A leading and trailing
+   slash have special meaning and are explained in the following.
+
+ - 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.
-
- - A leading slash matches the beginning of the pathname.
-   For example, "/{asterisk}.c" matches "cat-file.c" but not
-   "mozilla-sha1/sha1.c".
+   directory `foo`, 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 end with a slash, it would find a match
+   with a file or directory.
+
+ - The pattern is matched relative to the location of
+   the `.gitignore` file. Except if the pattern contains
+   no slash (or no slash but a trailing slash), then the pattern is
+   matched against all files and folders (recursively)
+   from the location of the `.gitignore` file.
+   For example, `doc/frotz/` matches `doc/frotz` directory, but not
+   a/doc/frotz`; however `frotz/` matches `frotz` and `a/frotz` that
+   is a directory (all paths are relative from the `.gitignore` file).
+
+ - If the pattern contains a leading slash, the pattern
+   is matched relative to the location of the
+   `.gitignore` file (this is actually a direct consequence
+   of the previous paragraph). For example, `/bar` only matches
+   the file or folder `bar` but not `a/bar`,
+   whereas the pattern `bar` would match both.
+
+ - An asterisk "`*`" matches anything except a slash.
+   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.
 
 Two consecutive asterisks ("`**`") in patterns matched against
 full pathname may have special meaning:
@@ -152,6 +163,22 @@ To stop tracking a file that is currently tracked, use
 EXAMPLES
 --------
 
+ - The pattern 'hello.*' matches any file or folder
+   whose name begins with 'hello'. If one wants to restrict
+   this only to the directory and not in its subdirectories,
+   one can prepend the pattern with a slash, i.e. '/hello.*';
+   the pattern now matches 'hello.txt', 'hello.c' but not
+   'a/hello.java'.
+
+ - The pattern `doc/frotz` and `/doc/frotz` have the same effect
+   in any `.gitignore` file. Both pattern match relative to the
+   location of the `.gitignore` file.
+
+ - The pattern "foo/*", matches "foo/test.json"
+   (a regular file), "foo/bar" (a directory), but it does not match
+   "foo/bar/hello.c" (a regular file), as the asterisk in the
+   pattern does not match "bar/hello.c" which has a slash in it.
+
 --------------------------------------------------------------
     $ git status
     [...]
-- 
2.17.1


             reply index

Thread overview: 36+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-06-02  9:04 Dr. Adam Nielsen [this message]
  -- strict thread matches above, loose matches on Subject: below --
2020-02-15  3:08 Pavel Ivashkov
2019-06-04 17:34 Dr. Adam Nielsen
2019-06-25 11:05 ` Dr. Adam Nielsen
2019-06-25 11:31   ` Philip Oakley
2019-06-27 17:10     ` Dr. Adam Nielsen
2019-07-04 10:40       ` Philip Oakley
2019-07-04 10:46         ` Philip Oakley
2019-06-27 17:43   ` Junio C Hamano
2019-05-31 18:17 Dr. Adam Nielsen
2019-05-31 18:16 Dr. Adam Nielsen
2019-05-31  7:44 Dr. Adam Nielsen
2019-05-31 16:30 ` Junio C Hamano
2019-05-31 17:24   ` Dr. Adam Nielsen
2019-05-31 17:40     ` Junio C Hamano
2019-06-01  9:33   ` Philip Oakley
2019-06-02  9:01     ` Dr. Adam Nielsen
2019-06-03 18:01     ` Junio C Hamano
2019-06-04 10:40       ` Philip Oakley
2019-06-01  9:23 ` Philip Oakley
2019-06-04 12:34 ` Philip Oakley
2019-06-04 17:22   ` Dr. Adam Nielsen
2019-05-18 14:13 Dr. Adam Nielsen
2019-05-19  1:59 ` Junio C Hamano
2019-05-19  6:59 ` Johannes Sixt
2019-05-18 14:07 Dr. Adam Nielsen
2019-05-18 19:34 ` Philip Oakley
2019-05-19 15:33   ` Dr. Adam Nielsen
     [not found]     ` <0c2894ce-7eab-8207-9af8-7ce5e779d4ec@iee.org>
2019-05-29  8:28       ` Dr. Adam Nielsen
2019-05-07 10:45 Dr. Adam Nielsen
2019-05-08  5:33 ` Junio C Hamano
2019-05-12  9:56   ` Dr. Adam Nielsen
2019-05-17 21:43     ` Dr. Adam Nielsen
2019-05-18  6:42       ` Johannes Sixt
2019-05-18 13:20         ` Dr. Adam Nielsen
2019-04-26 14:32 Dr. Adam Nielsen

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20190602090415.5889-1-admin@in-ici.net \
    --to=admin@in-ici.net \
    --cc=git@vger.kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

git@vger.kernel.org list mirror (unofficial, one of many)

Archives are clonable:
	git clone --mirror http://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

Example config snippet for mirrors

Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git
	nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git
	nntp://news.gmane.io/gmane.comp.version-control.git

 note: .onion URLs require Tor: https://www.torproject.org/

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git