docs: Clarify include/exclude documentation (#4072)

docs/usage_and_configuration/the_basics.md

@@ -241,24 +241,17 @@ Because of our [stability policy](../the_black_code_style/index.md), this will g
 stable formatting, but still allow you to take advantage of improvements that do not
 affect formatting.
 
-#### `--include`
-
-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.
-
 #### `--exclude`
 
 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
+directories on all platforms (Windows, too). By default, Black also ignores all paths
-later.
+listed in `.gitignore`. Changing this value will override all default exclusions.
 
 #### `--extend-exclude`
 
-Like `--exclude`, but adds additional files and directories on top of the excluded ones.
+Like `--exclude`, but adds additional files and directories on top of the default values
-Useful if you simply want to add to the default.
+instead of overriding them.
 
 #### `--force-exclude`
 
@@ -271,6 +264,13 @@ programmatically on changed files, such as in a pre-commit hook or editor plugin
 The name of the file when passing it through stdin. Useful to make sure Black will
 respect the `--force-exclude` option on some editors that rely on using stdin.
 
+#### `--include`
+
+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.
+
 #### `-W`, `--workers`
 
 When _Black_ formats multiple files, it may use a process pool to speed up formatting.

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:"
+        " By default, Black also ignores all paths listed in .gitignore. Changing this"
-        f" {DEFAULT_EXCLUDES}]"
+        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",