Repository: psf/black

Issue:
Usage of `--exclude` can be further clarified
**Is this related to a problem? Please describe.**

This issue is regarding the documentation [here](https://black.readthedocs.io/en/stable/usage_and_configuration/file_collection_and_discovery.html#gitignore). Setting `exclude` option will override the exclusions from .gitignore. Need to use the [extend-exclude](https://black.readthedocs.io/en/stable/usage_and_configuration/file_collection_and_discovery.html) instead. This is not well documented in the current user guide, with the assumption that the user will know the caveats.

**Describe the solution you'd like**

Update the documentation to explicitly saying that the `exlcude` option will override the .gitignore configurations.

**Describe alternatives you've considered**

No nothing and let the user bump into the situation.

**Additional context**





Discussion:
May I take this issue and submit a small PR? Currently I don't have access to push to the repo.
Feel free to submit a PR! Thanks for offering to contribute.

Resolving patch:
diff --git a/src/black/__init__.py b/src/black/__init__.py
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -344,19 +344,6 @@ def validate_regex(
         " either a major version number or an exact version."
     ),
 )
-@click.option(
-    "--include",
-    type=str,
-    default=DEFAULT_INCLUDES,
-    callback=validate_regex,
-    help=(
-        "A regular expression that matches files and directories that should be"
-        " included on recursive searches. An empty value means all files are included"
-        " regardless of the name. Use forward slashes for directories on all platforms"
-        " (Windows, too). Exclusions are calculated first, inclusions later."
-    ),
-    show_default=True,
-)
 @click.option(
     "--exclude",
     type=str,
@@ -365,8 +352,8 @@ def validate_regex(
         "A regular expression that matches files and directories that should be"
         " excluded on recursive searches. An empty value means no paths are excluded."
         " Use forward slashes for directories on all platforms (Windows, too)."
-        " Exclusions are calculated first, inclusions later. [default:"
-        f" {DEFAULT_EXCLUDES}]"
+        " By default, Black also ignores all paths listed in .gitignore. Changing this"
+        f" value will override all default exclusions. [default: {DEFAULT_EXCLUDES}]"
     ),
     show_default=False,
 )
@@ -376,7 +363,7 @@ def validate_regex(
     callback=validate_regex,
     help=(
         "Like --exclude, but adds additional files and directories on top of the"
-        " excluded ones. (Useful if you simply want to add to the default)"
+        " default values instead of overriding them."
     ),
 )
 @click.option(
@@ -398,6 +385,20 @@ def validate_regex(
         "editors that rely on using stdin."
     ),
 )
+@click.option(
+    "--include",
+    type=str,
+    default=DEFAULT_INCLUDES,
+    callback=validate_regex,
+    help=(
+        "A regular expression that matches files and directories that should be"
+        " included on recursive searches. An empty value means all files are included"
+        " regardless of the name. Use forward slashes for directories on all platforms"
+        " (Windows, too). Overrides all exclusions, including from .gitignore and"
+        " command line options."
+    ),
+    show_default=True,
+)
 @click.option(
     "-W",
     "--workers",


Test patch: