Reorganize docs v2 (GH-2174)

[etc/vim.git] / docs / usage_and_configuration / file_collection_and_discovery.md

diff --git a/docs/ignoring_unmodified_files.md b/docs/usage_and_configuration/file_collection_and_discovery.md
similarity index 61%
rename from docs/ignoring_unmodified_files.md
rename to docs/usage_and_configuration/file_collection_and_discovery.md
index a915f4e867806f4389518900db9f6598d0b9dbc7..54c76cd9a0f27f70f7e9b02e2700023a94677975 100644 (file)
--- a/docs/ignoring_unmodified_files.md
+++ b/docs/usage_and_configuration/file_collection_and_discovery.md
@@ -1,6 +1,11 @@
-[//]: # "NOTE: THIS FILE WAS AUTOGENERATED FROM README.md"
+# File collection and discovery
 
-# Ignoring unmodified files
+You can directly pass _Black_ files, but you can also pass directories and _Black_ will
+walk them, collecting files to format. It determines what files to format or skip
+automatically using the inclusion and exclusion regexes and as well their modification
+time.
+
+## Ignoring unmodified files
 
 _Black_ remembers files it has already formatted, unless the `--diff` flag is used or
 code is passed via standard input. This information is stored per-user. The exact
@@ -21,3 +26,12 @@ To override the location of these files on macOS or Linux, set the environment v
 `XDG_CACHE_HOME` to your preferred location. For example, if you want to put the cache
 in the directory you're running _Black_ from, set `XDG_CACHE_HOME=.cache`. _Black_ will
 then write the above files to `.cache/black/<version>/`.
+
+## .gitignore
+
+If `--exclude` is not set, _Black_ will automatically ignore files and directories in
+`.gitignore` file, if present. The `.gitignore` file must be in the project root to be
+used and nested `.gitignore` aren't supported.
+
+If you want _Black_ to continue using `.gitignore` while also configuring the exclusion
+rules, please use `--extend-exclude`.