README.md
1# ignore-walk
2
3[](https://travis-ci.org/npm/ignore-walk)
5
6Nested/recursive `.gitignore`/`.npmignore` parsing and filtering.
7
8Walk a directory creating a list of entries, parsing any `.ignore`
9files met along the way to exclude files.
10
11## USAGE
12
13```javascript
14const walk = require('ignore-walk')
15
16// All options are optional, defaults provided.
17
18// this function returns a promise, but you can also pass a cb
19// if you like that approach better.
20walk({
21 path: '...', // root dir to start in. defaults to process.cwd()
22 ignoreFiles: [ '.gitignore' ], // list of filenames. defaults to ['.ignore']
23 includeEmpty: true|false, // true to include empty dirs, default false
24 follow: true|false // true to follow symlink dirs, default false
25}, callback)
26
27// to walk synchronously, do it this way:
28const result = walk.sync({ path: '/wow/such/filepath' })
29```
30
31If you want to get at the underlying classes, they're at `walk.Walker`
32and `walk.WalkerSync`.
33
34## OPTIONS
35
36* `path` The path to start in. Defaults to `process.cwd()`
37
38* `ignoreFiles` Filenames to treat as ignore files. The default is
39 `['.ignore']`. (This is where you'd put `.gitignore` or
40 `.npmignore` or whatever.) If multiple ignore files are in a
41 directory, then rules from each are applied in the order that the
42 files are listed.
43
44* `includeEmpty` Set to `true` to include empty directories, assuming
45 they are not excluded by any of the ignore rules. If not set, then
46 this follows the standard `git` behavior of not including
47 directories that are empty.
48
49 Note: this will cause an empty directory to be included if it
50 would contain an included entry, even if it would have otherwise
51 been excluded itself.
52
53 For example, given the rules `*` (ignore everything) and `!/a/b/c`
54 (re-include the entry at `/a/b/c`), the directory `/a/b` will be
55 included if it is empty.
56
57* `follow` Set to `true` to treat symbolically linked directories as
58 directories, recursing into them. There is no handling for nested
59 symlinks, so `ELOOP` errors can occur in some cases when using this
60 option. Defaults to `false`.
61
){kind=link}