1 | [![Build Status](https://travis-ci.org/isaacs/rimraf.svg?branch=master)](https://travis-ci.org/isaacs/rimraf) [![Dependency Status](https://david-dm.org/isaacs/rimraf.svg)](https://david-dm.org/isaacs/rimraf) [![devDependency Status](https://david-dm.org/isaacs/rimraf/dev-status.svg)](https://david-dm.org/isaacs/rimraf#info=devDependencies)
|
2 |
|
3 | The [UNIX command](http://en.wikipedia.org/wiki/Rm_(Unix)) `rm -rf` for node.
|
4 |
|
5 | Install with `npm install rimraf`, or just drop rimraf.js somewhere.
|
6 |
|
7 | ## API
|
8 |
|
9 | `rimraf(f, [opts], callback)`
|
10 |
|
11 | The first parameter will be interpreted as a globbing pattern for files. If you
|
12 | want to disable globbing you can do so with `opts.disableGlob` (defaults to
|
13 | `false`). This might be handy, for instance, if you have filenames that contain
|
14 | globbing wildcard characters.
|
15 |
|
16 | The callback will be called with an error if there is one. Certain
|
17 | errors are handled for you:
|
18 |
|
19 | * Windows: `EBUSY` and `ENOTEMPTY` - rimraf will back off a maximum of
|
20 | `opts.maxBusyTries` times before giving up, adding 100ms of wait
|
21 | between each attempt. The default `maxBusyTries` is 3.
|
22 | * `ENOENT` - If the file doesn't exist, rimraf will return
|
23 | successfully, since your desired outcome is already the case.
|
24 | * `EMFILE` - Since `readdir` requires opening a file descriptor, it's
|
25 | possible to hit `EMFILE` if too many file descriptors are in use.
|
26 | In the sync case, there's nothing to be done for this. But in the
|
27 | async case, rimraf will gradually back off with timeouts up to
|
28 | `opts.emfileWait` ms, which defaults to 1000.
|
29 |
|
30 | ## options
|
31 |
|
32 | * unlink, chmod, stat, lstat, rmdir, readdir,
|
33 | unlinkSync, chmodSync, statSync, lstatSync, rmdirSync, readdirSync
|
34 |
|
35 | In order to use a custom file system library, you can override
|
36 | specific fs functions on the options object.
|
37 |
|
38 | If any of these functions are present on the options object, then
|
39 | the supplied function will be used instead of the default fs
|
40 | method.
|
41 |
|
42 | Sync methods are only relevant for `rimraf.sync()`, of course.
|
43 |
|
44 | For example:
|
45 |
|
46 | ```javascript
|
47 | var myCustomFS = require('some-custom-fs')
|
48 |
|
49 | rimraf('some-thing', myCustomFS, callback)
|
50 | ```
|
51 |
|
52 | * maxBusyTries
|
53 |
|
54 | If an `EBUSY`, `ENOTEMPTY`, or `EPERM` error code is encountered
|
55 | on Windows systems, then rimraf will retry with a linear backoff
|
56 | wait of 100ms longer on each try. The default maxBusyTries is 3.
|
57 |
|
58 | Only relevant for async usage.
|
59 |
|
60 | * emfileWait
|
61 |
|
62 | If an `EMFILE` error is encountered, then rimraf will retry
|
63 | repeatedly with a linear backoff of 1ms longer on each try, until
|
64 | the timeout counter hits this max. The default limit is 1000.
|
65 |
|
66 | If you repeatedly encounter `EMFILE` errors, then consider using
|
67 | [graceful-fs](http://npm.im/graceful-fs) in your program.
|
68 |
|
69 | Only relevant for async usage.
|
70 |
|
71 | * glob
|
72 |
|
73 | Set to `false` to disable [glob](http://npm.im/glob) pattern
|
74 | matching.
|
75 |
|
76 | Set to an object to pass options to the glob module. The default
|
77 | glob options are `{ nosort: true, silent: true }`.
|
78 |
|
79 | Glob version 6 is used in this module.
|
80 |
|
81 | Relevant for both sync and async usage.
|
82 |
|
83 | * disableGlob
|
84 |
|
85 | Set to any non-falsey value to disable globbing entirely.
|
86 | (Equivalent to setting `glob: false`.)
|
87 |
|
88 | ## rimraf.sync
|
89 |
|
90 | It can remove stuff synchronously, too. But that's not so good. Use
|
91 | the async API. It's better.
|
92 |
|
93 | ## CLI
|
94 |
|
95 | If installed with `npm install rimraf -g` it can be used as a global
|
96 | command `rimraf <path> [<path> ...]` which is useful for cross platform support.
|
97 |
|
98 | ## mkdirp
|
99 |
|
100 | If you need to create a directory recursively, check out
|
101 | [mkdirp](https://github.com/substack/node-mkdirp).
|