Tip: set explore_excluded_dirs to false

If your repository contains large directories that are excluded by exclude_files (for example, node_modules or venv), you can get a big performance boost by setting explore_excluded_dirs = false in the config.

Keep in mind that this only applies when the directory itself is ignored. For example:

• exclude_files = [ '**/node_modules' ] will skip exploring the contents of all directories named node_modules.
• exclude_files = [ '**/node_modules/**' ] will check the direct children of the directory, and will ignore (+ skip exploring) each of them, unless they match include_files.

What if I want to skip most directories, but I need to include a specific file?

Suppose that you want to exclude all the files in some-dir except for some-dir/images/important.png. This situation is unusual and you should probably just move that file out of the ignored directory. However, if that is not an option, you can either keep explore_excluded_dirs=true or you can do the following:

explore_excluded_dirs = false  #  :)

# Exclude all children of some-dir, but not some-dir itself, so that it can be explored
exclude_files = [ "some-dir/**" ]
include_files = [
    # Include images so that it can be explored. Children are NOT included (no trailing `/**`)
    "some-dir/images",
    "some-dir/images/important.png"  # Include the file you want
]

This keeps the amount of checked files at a minimum (only the direct descendants of some-dir and some-dir/images) while achieving the same behavior as this equivalent (but slower) config:

explore_excluded_dirs = true  #  :(
exclude_files = [ "some-dir" ]
include_files = [ "some-dir/images/important.png" ]

If disabling explore_excluded_dirs is so good, why does it default to true?

I expect that most users won't have large ignored directories in their dotfiles, and allowing include_files to match files inside excluded directories is certainly more intuitive (just look at the difference between the previous 2 configs).

Still, the previous example is a bit contrived and I believe that in 99% of cases it's safe to just set explore_excluded_dirs to false and forget about it. I just wanted you to have read this text, so you can make a conscious decision while knowing the tradeoffs it implies.