What is rimraf?
The rimraf npm package is a Node.js module that provides a way to perform a deep deletion of files and directories, similar to the 'rm -rf' Unix command. It is designed to work on both Windows and Unix file systems, handling the intricacies of different environments. It is often used to clean up directories before rebuilding a project or to remove temporary files.
What are rimraf's main functionalities?
Asynchronous file and directory removal
This feature allows for the asynchronous removal of a directory and its contents. The provided code sample demonstrates how to use rimraf to delete a directory asynchronously. The callback function is used to handle any errors or to perform actions after the removal is complete.
const rimraf = require('rimraf');
rimraf('/path/to/directory', function (err) {
if (err) throw err;
console.log('Directory and its contents have been removed');
});
Synchronous file and directory removal
This feature allows for the synchronous removal of a directory and its contents. The provided code sample demonstrates how to use rimraf to delete a directory synchronously. The operation will block the event loop until the removal is complete.
const rimraf = require('rimraf');
rimraf.sync('/path/to/directory');
console.log('Directory and its contents have been removed synchronously');
Promisified file and directory removal
This feature allows for the removal of a directory and its contents using promises, which can be more convenient when working with modern asynchronous code patterns. The provided code sample demonstrates how to promisify the rimraf function and use it with then/catch for handling the resolution and rejection of the promise.
const rimraf = require('rimraf');
const { promisify } = require('util');
const rimrafPromise = promisify(rimraf);
rimrafPromise('/path/to/directory').then(() => {
console.log('Directory and its contents have been removed');
}).catch((err) => {
console.error('An error occurred:', err);
});
Other packages similar to rimraf
fs-extra
fs-extra is a package that extends the built-in fs module with additional methods, including 'remove' and 'removeSync', which are similar to rimraf's functionality. It offers a broader set of file system operations, making it a more comprehensive choice for projects that require more than just file removal.
del
del is a package that provides file and directory deletion features with a promise-based API. It is similar to rimraf but offers more options for file selection and deletion, such as pattern matching. It is a good choice for users who prefer working with promises and need more control over what files to delete.
![devDependency Status](https://david-dm.org/isaacs/rimraf/dev-status.svg)
The UNIX command rm -rf
for node.
Install with npm install rimraf
, or just drop rimraf.js somewhere.
API
rimraf(f, [opts], callback)
The first parameter will be interpreted as a globbing pattern for files. If you
want to disable globbing you can do so with opts.disableGlob
(defaults to
false
). This might be handy, for instance, if you have filenames that contain
globbing wildcard characters.
The callback will be called with an error if there is one. Certain
errors are handled for you:
- Windows:
EBUSY
and ENOTEMPTY
- rimraf will back off a maximum of
opts.maxBusyTries
times before giving up, adding 100ms of wait
between each attempt. The default maxBusyTries
is 3. ENOENT
- If the file doesn't exist, rimraf will return
successfully, since your desired outcome is already the case.EMFILE
- Since readdir
requires opening a file descriptor, it's
possible to hit EMFILE
if too many file descriptors are in use.
In the sync case, there's nothing to be done for this. But in the
async case, rimraf will gradually back off with timeouts up to
opts.emfileWait
ms, which defaults to 1000.
options
-
unlink, chmod, stat, lstat, rmdir, readdir,
unlinkSync, chmodSync, statSync, lstatSync, rmdirSync, readdirSync
In order to use a custom file system library, you can override
specific fs functions on the options object.
If any of these functions are present on the options object, then
the supplied function will be used instead of the default fs
method.
Sync methods are only relevant for rimraf.sync()
, of course.
For example:
var myCustomFS = require('some-custom-fs')
rimraf('some-thing', myCustomFS, callback)
-
maxBusyTries
If an EBUSY
, ENOTEMPTY
, or EPERM
error code is encountered
on Windows systems, then rimraf will retry with a linear backoff
wait of 100ms longer on each try. The default maxBusyTries is 3.
Only relevant for async usage.
-
emfileWait
If an EMFILE
error is encountered, then rimraf will retry
repeatedly with a linear backoff of 1ms longer on each try, until
the timeout counter hits this max. The default limit is 1000.
If you repeatedly encounter EMFILE
errors, then consider using
graceful-fs in your program.
Only relevant for async usage.
-
glob
Set to false
to disable glob pattern
matching.
Set to an object to pass options to the glob module. The default
glob options are { nosort: true, silent: true }
.
Glob version 6 is used in this module.
Relevant for both sync and async usage.
-
disableGlob
Set to any non-falsey value to disable globbing entirely.
(Equivalent to setting glob: false
.)
rimraf.sync
It can remove stuff synchronously, too. But that's not so good. Use
the async API. It's better.
CLI
If installed with npm install rimraf -g
it can be used as a global
command rimraf <path> [<path> ...]
which is useful for cross platform support.
mkdirp
If you need to create a directory recursively, check out
mkdirp.