docs/usage_and_configuration/file_collection_and_discovery.md

   1 # File collection and discovery
   2
   3 You can directly pass _Black_ files, but you can also pass directories and _Black_ will
   4 walk them, collecting files to format. It determines what files to format or skip
   5 automatically using the inclusion and exclusion regexes and as well their modification
   6 time.
   7
   8 ## Ignoring unmodified files
   9
  10 _Black_ remembers files it has already formatted, unless the `--diff` flag is used or
  11 code is passed via standard input. This information is stored per-user. The exact
  12 location of the file depends on the _Black_ version and the system on which _Black_ is
  13 run. The file is non-portable. The standard location on common operating systems is:
  14
  15 - Windows:
  16   `C:\\Users\<username>\AppData\Local\black\black\Cache\<version>\cache.<line-length>.<file-mode>.pickle`
  17 - macOS:
  18   `/Users/<username>/Library/Caches/black/<version>/cache.<line-length>.<file-mode>.pickle`
  19 - Linux:
  20   `/home/<username>/.cache/black/<version>/cache.<line-length>.<file-mode>.pickle`
  21
  22 `file-mode` is an int flag that determines whether the file was formatted as 3.6+ only,
  23 as .pyi, and whether string normalization was omitted.
  24
  25 To override the location of these files on all systems, set the environment variable
  26 `BLACK_CACHE_DIR` to the preferred location. Alternatively on macOS and Linux, set
  27 `XDG_CACHE_HOME` to your preferred location. For example, if you want to put the cache
  28 in the directory you're running _Black_ from, set `BLACK_CACHE_DIR=.cache/black`.
  29 _Black_ will then write the above files to `.cache/black`. Note that `BLACK_CACHE_DIR`
  30 will take precedence over `XDG_CACHE_HOME` if both are set.
  31
  32 ## .gitignore
  33
  34 If `--exclude` is not set, _Black_ will automatically ignore files and directories in
  35 `.gitignore` file(s), if present.
  36
  37 If you want _Black_ to continue using `.gitignore` while also configuring the exclusion
  38 rules, please use `--extend-exclude`.