Configuration example "exclude" doesn't work as documented

[orn688]

Describe the bug A clear and concise description of what the bug is.

The example pyproject.toml shown in the Configuration format section of the README has the following exclude:

[tool.black]
line-length = 88
target-version = ['py37']
include = '\.pyi?$'
exclude = '''

(
  /(
      \.eggs         # exclude a few common directories in the
    | \.git          # root of the project
    | \.hg
    | \.mypy_cache
    | \.tox
    | \.venv
    | _build
    | buck-out
    | build
    | dist
  )/
  | foo.py           # also separately exclude a file named foo.py in
                     # the root of the project
)
'''

However, the comment next to foo.py seems to be incorrect. That foo.py will actually exclude any foo.py found in the project, not just in the root.

To Reproduce Steps to reproduce the behavior:

1. mkdir temp && cd temp
2. Create pyproject.toml containing the example configuration from above
3. touch foo.py
4. mkdir bar
5. touch bar/foo.py
6. black --verbose . prints the following:

   Using configuration from /path/to/temp/pyproject.toml.
   foo.py ignored: matches the --exclude regular expression
   bar/foo.py ignored: matches the --exclude regular expression
   No Python files are present to be formatted. Nothing to do 😴
   

Expected behavior A clear and concise description of what you expected to happen.

I would expect Black to not exclude bar/foo.py. It would be nice if there were a way to actually accomplish what the example says (i.e., only exclude foo.py in the project root). Short of that, I think the documentation could use rewording to avoid suggesting that the example pyproject.toml only excludes foo.py in the project root.

Environment (please complete the following information):

• Version: master
• OS and Python version: Linux/Python 3.7.7

Does this bug also happen on master? yes

[sittingbool]

Same on MaxOSX and Python 3.8

[orn688]

Update: you can exclude a file only if it's in the root of the project by prepending ^/ to the path. / represents the root of the directory, but you additionally need the ^ because Black uses re.search() to check whether the exclude regex matches each path. Unlike re.match() which only checks for matches at the beginning of the string, re.search() checks for matches anywhere in the string, which is why you need the ^ to anchor matches to the beginning of the exclude string.

So I think the README example should be updated to this:

exclude = '''
^/(
  (
      \.eggs         # exclude a few common directories in the
    | \.git          # root of the project
    | \.hg
    | \.mypy_cache
    | \.tox
    | \.venv
    | _build
    | buck-out
    | build
    | dist
  )/
  | foo.py           # also separately exclude a file named foo.py in
                     # the root of the project
)
'''

(Note that the forward slash before the second opening paren has been moved to precede the first opening paren so it applies to foo.py as well, and is now also preceded by a ^.)

Black's default exclude might also need to be updated – the default exclude it caused issues for my team when we started using Black because we have a library called build in our project that's nested under a subdirectory of the root. But Black still skipped formatting it because it excludes build directories at any nesting level.

[ichard26]

Closing as this was fixed by #1861, thank you @orn688 for both reporting and fixing!