Documentation example `--extend-exclude ^/foo.py` does not exclude root file `foo.py`

Describe the bug Black does not exclude the filefoo.py root when asked to exclude it with ^/foo.py. This particular example was used in the documentation:

extend-exclude = '''
# A regex preceded with ^/ will apply only to files and directories
# in the root of the project.
^/foo.py  # exclude a file named foo.py in the root of the project (in addition to the defaults)
'''

To Reproduce Start with an empty directory

$ echo "s='test'" > foo.py

$ black --extend-exclude "^/foo.py" --check .
would reformat foo.py
Oh no! 💥 💔 💥
1 file would be reformatted.

Same behavior using --exclude flag

Environment

• Black’s version: 21.12b0
• OS and Python version: OSX 11.6, Python 3.9.6

[ketozhang]

I don’t think that particular modification would help since for the case of pyproject file, the root is always the path of the pyproject file.

A section on general examples of exclusion patterns will help:

• foo exclude any file or directory if its path has this substring
• ^/foo$, exclude file or directory on project root (see Where Black looks for the file) Make sure to end with $; without it, directories like foobar/ will be excluded.
• foo\/ exclude any directory if its path has this substring

Largely needed since everyone makes the mistake of attempting to use glob patterns (e.g., \.\/foo and ^foo\/ doesn’t work as intended)

[tomschr]

I had the same problem and circumvent it by using Git’s .gitignore and adding my excludes:

# .gitignore file
/foo.py

If you want to ignore all Python files in the project’s root dir (but not setup.py, for example) you could add these lines:

/*.py
!/setup.py

I’ve prepared a small environment to show how it looks like (see below for details). When I run black in verbose mode I get:

$ black --verbose --check .
Identified `/tmp/gitblack` as project root containing a .git directory.
Sources to be formatted: "."
.git ignored: matches the --exclude regular expression
foo.py ignored: matches the .gitignore file content
setup.py already well formatted, good job.
src/foo/foo.py already well formatted, good job.

All done! ✨ 🍰 ✨
2 files would be left unchanged.

Maybe this is not intended, but perhaps it’s even better to have all the ignores in the .gitignore file anyway. If I don’t want to reformat or check the source code of a Python file in the project’s root directory, it shouldn’t be included in the Git repo anyway.

Details about the test Git repo

$ mkdir -p /tmp/gitblack && cd /tmp/gitblack
$ git init .
$ mkdir -p src/foo/
$ touch foo.py src/foo/foo.py setup.py
$ cat << EOF > .gitignore
/*.py
!/setup.py
EOF
$ git add .gitignore setup.py src/foo/foo.py
$ git commit -m "Initial import"