1 | The [UNIX command](<http://en.wikipedia.org/wiki/Rm_(Unix)>) `rm -rf` for node.
|
2 |
|
3 | Install with `npm install rimraf`.
|
4 |
|
5 | ## Major Changes
|
6 |
|
7 | ### v4 to v5
|
8 |
|
9 | - There is no default export anymore. Import the functions directly
|
10 | using, e.g., `import { rimrafSync } from 'rimraf`.
|
11 |
|
12 | ### v3 to v4
|
13 |
|
14 | - The function returns a `Promise` instead of taking a callback.
|
15 | - Globbing requires the `--glob` CLI option or `glob` option property
|
16 | to be set. (Removed in 4.0 and 4.1, opt-in support added in 4.2.)
|
17 | - Functions take arrays of paths, as well as a single path.
|
18 | - Native implementation used by default when available, except on
|
19 | Windows, where this implementation is faster and more reliable.
|
20 | - New implementation on Windows, falling back to "move then
|
21 | remove" strategy when exponential backoff for `EBUSY` fails to
|
22 | resolve the situation.
|
23 | - Simplified implementation on Posix, since the Windows
|
24 | affordances are not necessary there.
|
25 | - As of 4.3, return/resolve value is boolean instead of undefined
|
26 |
|
27 | ## API
|
28 |
|
29 | Hybrid module, load either with `import` or `require()`.
|
30 |
|
31 | ```js
|
32 | // 'rimraf' export is the one you probably want, but other
|
33 | // strategies exported as well.
|
34 | import { rimraf, rimrafSync, native, nativeSync } from 'rimraf'
|
35 | // or
|
36 | const { rimraf, rimrafSync, native, nativeSync } = require('rimraf')
|
37 | ```
|
38 |
|
39 | All removal functions return a boolean indicating that all
|
40 | entries were successfully removed.
|
41 |
|
42 | The only case in which this will not return `true` is if
|
43 | something was omitted from the removal via a `filter` option.
|
44 |
|
45 | ### `rimraf(f, [opts]) -> Promise`
|
46 |
|
47 | This first parameter is a path or array of paths. The second
|
48 | argument is an options object.
|
49 |
|
50 | Options:
|
51 |
|
52 | - `preserveRoot`: If set to boolean `false`, then allow the
|
53 | recursive removal of the root directory. Otherwise, this is
|
54 | not allowed.
|
55 | - `tmp`: Windows only. Temp folder to use to place files and
|
56 | folders for the "move then remove" fallback. Must be on the
|
57 | same physical device as the path being deleted. Defaults to
|
58 | `os.tmpdir()` when that is on the same drive letter as the path
|
59 | being deleted, or `${drive}:\temp` if present, or `${drive}:\`
|
60 | if not.
|
61 | - `maxRetries`: Windows and Native only. Maximum number of
|
62 | retry attempts in case of `EBUSY`, `EMFILE`, and `ENFILE`
|
63 | errors. Default `10` for Windows implementation, `0` for Native
|
64 | implementation.
|
65 | - `backoff`: Windows only. Rate of exponential backoff for async
|
66 | removal in case of `EBUSY`, `EMFILE`, and `ENFILE` errors.
|
67 | Should be a number greater than 1. Default `1.2`
|
68 | - `maxBackoff`: Windows only. Maximum total backoff time in ms to
|
69 | attempt asynchronous retries in case of `EBUSY`, `EMFILE`, and
|
70 | `ENFILE` errors. Default `200`. With the default `1.2` backoff
|
71 | rate, this results in 14 retries, with the final retry being
|
72 | delayed 33ms.
|
73 | - `retryDelay`: Native only. Time to wait between retries, using
|
74 | linear backoff. Default `100`.
|
75 | - `signal` Pass in an AbortSignal to cancel the directory
|
76 | removal. This is useful when removing large folder structures,
|
77 | if you'd like to limit the amount of time spent.
|
78 |
|
79 | Using a `signal` option prevents the use of Node's built-in
|
80 | `fs.rm` because that implementation does not support abort
|
81 | signals.
|
82 |
|
83 | - `glob` Boolean flag to treat path as glob pattern, or an object
|
84 | specifying [`glob` options](https://github.com/isaacs/node-glob).
|
85 | - `filter` Method that returns a boolean indicating whether that
|
86 | path should be deleted. With async rimraf methods, this may
|
87 | return a Promise that resolves to a boolean. (Since Promises
|
88 | are truthy, returning a Promise from a sync filter is the same
|
89 | as just not filtering anything.)
|
90 |
|
91 | The first argument to the filter is the path string. The
|
92 | second argument is either a `Dirent` or `Stats` object for that
|
93 | path. (The first path explored will be a `Stats`, the rest
|
94 | will be `Dirent`.)
|
95 |
|
96 | If a filter method is provided, it will _only_ remove entries
|
97 | if the filter returns (or resolves to) a truthy value. Omitting
|
98 | a directory will still allow its children to be removed, unless
|
99 | they are also filtered out, but any parents of a filtered entry
|
100 | will not be removed, since the directory would not be empty in
|
101 | that case.
|
102 |
|
103 | Using a filter method prevents the use of Node's built-in
|
104 | `fs.rm` because that implementation does not support filtering.
|
105 |
|
106 | Any other options are provided to the native Node.js `fs.rm` implementation
|
107 | when that is used.
|
108 |
|
109 | This will attempt to choose the best implementation, based on Node.js
|
110 | version and `process.platform`. To force a specific implementation, use
|
111 | one of the other functions provided.
|
112 |
|
113 | ### `rimraf.sync(f, [opts])` `rimraf.rimrafSync(f, [opts])`
|
114 |
|
115 | Synchronous form of `rimraf()`
|
116 |
|
117 | Note that, unlike many file system operations, the synchronous form will
|
118 | typically be significantly _slower_ than the async form, because recursive
|
119 | deletion is extremely parallelizable.
|
120 |
|
121 | ### `rimraf.native(f, [opts])`
|
122 |
|
123 | Uses the built-in `fs.rm` implementation that Node.js provides. This is
|
124 | used by default on Node.js versions greater than or equal to `14.14.0`.
|
125 |
|
126 | ### `rimraf.nativeSync(f, [opts])` `rimraf.native.sync(f, [opts])`
|
127 |
|
128 | Synchronous form of `rimraf.native`
|
129 |
|
130 | ### `rimraf.manual(f, [opts])`
|
131 |
|
132 | Use the JavaScript implementation appropriate for your operating system.
|
133 |
|
134 | ### `rimraf.manualSync(f, [opts])` `rimraf.manualSync(f, opts)`
|
135 |
|
136 | Synchronous form of `rimraf.manual()`
|
137 |
|
138 | ### `rimraf.windows(f, [opts])`
|
139 |
|
140 | JavaScript implementation of file removal appropriate for Windows
|
141 | platforms. Works around `unlink` and `rmdir` not being atomic
|
142 | operations, and `EPERM` when deleting files with certain
|
143 | permission modes.
|
144 |
|
145 | First deletes all non-directory files within the tree, and then
|
146 | removes all directories, which should ideally be empty by that
|
147 | time. When an `ENOTEMPTY` is raised in the second pass, falls
|
148 | back to the `rimraf.moveRemove` strategy as needed.
|
149 |
|
150 | ### `rimraf.windows.sync(path, [opts])` `rimraf.windowsSync(path, [opts])`
|
151 |
|
152 | Synchronous form of `rimraf.windows()`
|
153 |
|
154 | ### `rimraf.moveRemove(path, [opts])`
|
155 |
|
156 | Moves all files and folders to the parent directory of `path`
|
157 | with a temporary filename prior to attempting to remove them.
|
158 |
|
159 | Note that, in cases where the operation fails, this _may_ leave
|
160 | files lying around in the parent directory with names like
|
161 | `.file-basename.txt.0.123412341`. Until the Windows kernel
|
162 | provides a way to perform atomic `unlink` and `rmdir` operations,
|
163 | this is unfortunately unavoidable.
|
164 |
|
165 | To move files to a different temporary directory other than the
|
166 | parent, provide `opts.tmp`. Note that this _must_ be on the same
|
167 | physical device as the folder being deleted, or else the
|
168 | operation will fail.
|
169 |
|
170 | This is the slowest strategy, but most reliable on Windows
|
171 | platforms. Used as a last-ditch fallback by `rimraf.windows()`.
|
172 |
|
173 | ### `rimraf.moveRemove.sync(path, [opts])` `rimraf.moveRemoveSync(path, [opts])`
|
174 |
|
175 | Synchronous form of `rimraf.moveRemove()`
|
176 |
|
177 | ### Command Line Interface
|
178 |
|
179 | ```
|
180 | rimraf version 4.3.0
|
181 |
|
182 | Usage: rimraf <path> [<path> ...]
|
183 | Deletes all files and folders at "path", recursively.
|
184 |
|
185 | Options:
|
186 | -- Treat all subsequent arguments as paths
|
187 | -h --help Display this usage info
|
188 | --preserve-root Do not remove '/' recursively (default)
|
189 | --no-preserve-root Do not treat '/' specially
|
190 | -G --no-glob Treat arguments as literal paths, not globs (default)
|
191 | -g --glob Treat arguments as glob patterns
|
192 | -v --verbose Be verbose when deleting files, showing them as
|
193 | they are removed. Not compatible with --impl=native
|
194 | -V --no-verbose Be silent when deleting files, showing nothing as
|
195 | they are removed (default)
|
196 | -i --interactive Ask for confirmation before deleting anything
|
197 | Not compatible with --impl=native
|
198 | -I --no-interactive Do not ask for confirmation before deleting
|
199 |
|
200 | --impl=<type> Specify the implementation to use:
|
201 | rimraf: choose the best option (default)
|
202 | native: the built-in implementation in Node.js
|
203 | manual: the platform-specific JS implementation
|
204 | posix: the Posix JS implementation
|
205 | windows: the Windows JS implementation (falls back to
|
206 | move-remove on ENOTEMPTY)
|
207 | move-remove: a slow reliable Windows fallback
|
208 |
|
209 | Implementation-specific options:
|
210 | --tmp=<path> Temp file folder for 'move-remove' implementation
|
211 | --max-retries=<n> maxRetries for 'native' and 'windows' implementations
|
212 | --retry-delay=<n> retryDelay for 'native' implementation, default 100
|
213 | --backoff=<n> Exponential backoff factor for retries (default: 1.2)
|
214 | ```
|
215 |
|
216 | ## mkdirp
|
217 |
|
218 | If you need to _create_ a directory recursively, check out
|
219 | [mkdirp](https://github.com/isaacs/node-mkdirp).
|