Issue #16695: Document how glob handles filenames starting with a dot

3 files changed, 24 insertions, 4 deletions

diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst
index b881a30..75f67b9 100644
--- a/Doc/library/glob.rst
+++ b/Doc/library/glob.rst
@@ -16,8 +16,10 @@ according to the rules used by the Unix shell.  No tilde expansion is done, but
 ``*``, ``?``, and character ranges expressed with ``[]`` will be correctly
 matched.  This is done by using the :func:`os.listdir` and
 :func:`fnmatch.fnmatch` functions in concert, and not by actually invoking a
-subshell.  (For tilde and shell variable expansion, use
-:func:`os.path.expanduser` and :func:`os.path.expandvars`.)
+subshell.  Note that unlike :func:`fnmatch.fnmatch`, :mod:`glob` treats
+filenames beginning with a dot (``.``) as special cases.  (For tilde and shell
+variable expansion, use :func:`os.path.expanduser` and
+:func:`os.path.expandvars`.)
 
 For a literal match, wrap the meta-characters in brackets.
 For example, ``'[?]'`` matches the character ``'?'``.
@@ -52,6 +54,15 @@ preserved. ::
    >>> glob.glob('?.gif')
    ['1.gif']
 
+If the directory contains files starting with ``.`` they won't be matched by
+default. For example, consider a directory containing :file:`card.gif` and
+:file:`.card.gif`::
+
+   >>> import glob
+   >>> glob.glob('*.gif')
+   ['card.gif']
+   >>> glob.glob('.c*')
+   ['.card.gif']
 
 .. seealso::
 
diff --git a/Lib/glob.py b/Lib/glob.py
index 0aee605..f34534b 100644
--- a/Lib/glob.py
+++ b/Lib/glob.py
@@ -18,7 +18,10 @@ __all__ = ["glob", "iglob"]
 def glob(pathname):
     """Return a list of paths matching a pathname pattern.
 
-    The pattern may contain simple shell-style wildcards a la fnmatch.
+    The pattern may contain simple shell-style wildcards a la
+    fnmatch. However, unlike fnmatch, filenames starting with a
+    dot are special cases that are not matched by '*' and '?'
+    patterns.
 
     """
     return list(iglob(pathname))
@@ -26,7 +29,10 @@ def glob(pathname):
 def iglob(pathname):
     """Return an iterator which yields the paths matching a pathname pattern.
 
-    The pattern may contain simple shell-style wildcards a la fnmatch.
+    The pattern may contain simple shell-style wildcards a la
+    fnmatch. However, unlike fnmatch, filenames starting with a
+    dot are special cases that are not matched by '*' and '?'
+    patterns.
 
     """
     if not has_magic(pathname):
diff --git a/Misc/NEWS b/Misc/NEWS
index 926593a..9f2a2be 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -926,6 +926,9 @@ Tools/Demos
 Documentation
 -------------
 
+- Issue #16695: Document how glob handles filenames starting with a
+  dot. Initial patch by Jyrki Pulliainen.
+
 - Issue #8890: Stop advertising an insecure practice by replacing uses
   of the /tmp directory with better alternatives in the documentation.
   Patch by Geoff Wilson.