readme.md
1[](http://travis-ci.org/soldair/node-walkdir)
2
3## walkdir
4
5Find files. Walks a directory tree emitting events based on what it finds. Presents a familliar callback/emitter/sync interface. Walk a tree of any depth. This is a performant option any pull requests to make it more so will be taken into consderation..
6
7## Example
8
9```js
10
11var walk = require('walkdir');
12
13//async with path callback
14
15walk('../', function(path, stat) {
16 console.log('found: ', path);
17});
18
19//use async emitter to capture more events
20
21var emitter = walk('../');
22
23emitter.on('file', function(filename, stat) {
24 console.log('file from emitter: ', filename);
25});
26
27
28//sync with callback
29
30walk.sync('../', function(path, stat) {
31 console.log('found sync:', path);
32});
33
34//sync just need paths
35
36var paths = walk.sync('../');
37console.log('found paths sync: ', paths);
38
39```
40
41
42## install
43
44 npm install walkdir
45
46## arguments
47
48walkdir(path, [options], [callback])
49walkdir.sync(path, [options], [callback]);
50
51- path
52 - the starting point of your directory walk
53
54- options. supported options are
55 - general
56
57 ```js
58 {
59 "follow_symlinks": false, // default is off
60 "no_recurse": false, // only recurse one level deep
61 "max_depth": undefined // only recurse down to max_depth. if you need more than no_recurse
62 "track_inodes": true // on windows or with hardlinks some files are not emitted due to inode collision.
63 // ^ should be used with max_depth to prevent infinite loop
64 }
65 ```
66
67 - sync only
68
69 ```js
70 {
71 "return_object": false, // if true the sync return will be in {path:stat} format instead of [path,path,...]
72 "no_return": false, // if true null will be returned and no array or object will be created with found paths. useful for large listings
73 }
74 ```
75
76- callback
77 - this is bound to the path event of the emitter. its optional in all cases.
78
79 ```js
80 callback(path, stat)
81 ```
82
83## events
84
85non error type events are emitted with (path,stat). stat is an instanceof fs.Stats
86
87###path
88fired for everything
89
90###file
91fired only for regular files
92
93###directory
94fired only for directories
95
96###link
97fired when a symbolic link is found
98
99###end
100fired when the entire tree has been read and emitted.
101
102###socket
103fired when a socket descriptor is found
104
105###fifo
106fired when a fifo is found
107
108###characterdevice
109fired when a character device is found
110
111###blockdevice
112fired when a block device is found
113
114###targetdirectory
115fired for the stat of the path you provided as the first argument. is is only fired if it is a directory.
116
117###empty
118fired for empty directory
119
120## error events
121error type events are emitted with (path,error). error being the error object returned from an fs call or other opperation.
122
123###error
124if the target path cannot be read an error event is emitted. this is the only failure case.
125
126###fail
127when stat or read fails on a path somewhere in the walk and it is not your target path you get a fail event instead of error.
128This is handy if you want to find places you dont have access too.
129
130## notes
131the async emitter returned supports 3 methods
132
133###end
134 stop a walk in progress
135
136###pause
137 pause the walk. no more events will be emitted until resume
138
139###resume
140 resume the walk
141
142### ignore(path or array of paths)
143 will not traverse these directories. may be called in the path event handler to ignore dynamically.
144 ```js
145 var walk = require('walkdir');
146 var p = require('path');
147 walk('/', function(path, stat) {
148 // ignore all .git directories.
149 if (p.basename(path) === '.git') {
150 this.ignore(path)
151 }
152 })
153 ```
154
155### cancel a walk in progress
156 ```js
157 //cancel a walk in progress within callback.
158
159 var walk = require('walkdir');
160 walk('../', function(path, stat) {
161 this.end();
162 });
163
164 //cancel a walk in progress with emitter handle
165 var walk = require('walkdir');
166 var emitter = walk('../');
167
168 doSomethingAsync(function() {
169 emitter.end();
170 })
171 ```
172
173## thanks
174thanks to substack. the interface for this module is based off of node-findit
175
176## contributing
177see `CONTRIBUTING.md` for guidelines. this is an open opensource project.
178
179
){kind=link}