DOCSEARCHbyAlgolia
Submit Docs

rimraf

repository·main·Indexed 25 days ago

https://github.com/isaacs/rimraf

A cross-platform deep deletion module for Node.js (version 6.1.3) that implements the UNIX `rm -rf` command. It provides an asynchronous API returning a Promise, a synchronous `rimraf.sync` method, and a CLI tool for recursively removing files and directories. The library supports globbing patterns, custom filters, and multiple implementation strategies including native (Node.js `fs.rm`), manual, and Windows-optimized versions with retry and backoff logic.

Tokens
2.2K
Snippets
5
Records
20
Agent score
91%

What's inside rimraf

  3. Use rimraf.sync() for synchronous removal

    main
    Use rimraf.sync(f, [opts]) (also exported as rimraf.rimrafSync) for synchronous file removal. Note that the synchronous form is typically significantly slower than the async form because recursive deletion is highly parallelizable.

  4. Use the rimraf async API

    main

    The primary async function is rimraf(f, [opts], callback).

    • f: A path or a globbing pattern.
    • opts: An optional configuration object.
    • callback: A function called with an error if one occurs.

    Note on Globbing: The first parameter is interpreted as a globbing pattern by default. To treat the path as a literal string and disable globbing, set opts.disableGlob to a truthy value or opts.glob to false.

  5. Use specific rimraf implementations

    main

    While rimraf() chooses the best implementation automatically, you can force a specific strategy:

    • rimraf.native(f, [opts]): Uses Node.js built-in fs.rm. Default for Node >= 14.14.0.
    • rimraf.manual(f, [opts]): Uses the platform-specific JavaScript implementation.
    • rimraf.windows(f, [opts]): JavaScript implementation optimized for Windows (handles EPERM and non-atomic operations).
    • rimraf.moveRemove(f, [opts]): A slow but highly reliable Windows fallback that moves files to a temporary location before deletion.

  6. Import rimraf functions

    main

    The module is a hybrid module that supports both ESM import and CommonJS require(). The main rimraf export is the recommended way to use the library as it automatically chooses the best implementation based on your Node.js version and platform. Other specific strategies are also exported.

    // ESM
import { rimraf, rimrafSync, native, nativeSync } from 'rimraf'

// CommonJS
const { rimraf, rimrafSync, native, nativeSync } = require('rimraf')

  8. Use the rimraf() async function

    main
    The primary async function rimraf(f, [opts]) accepts a path or an array of paths. It returns a Promise that resolves to a boolean indicating whether all entries were successfully removed. The only case where it returns false is if an entry was omitted due to a filter option.

  9. Reference rimraf CLI flags

    main

    The following flags are available for the rimraf CLI:

    Usage: rimraf <path> [<path> ...]

Options:
  --                   Treat all subsequent arguments as paths
  -h --help            Display this usage info
  --version            Display version
  --preserve-root      Do not remove '/' recursively (default)
  --no-preserve-root   Do not treat '/' specially
  -G --no-glob         Treat arguments as literal paths, not globs (default)
  -g --glob            Treat arguments as glob patterns
  -v --verbose         Be verbose when deleting files, showing them as they are removed. Not compatible with --impl=native
  -V --no-verbose     Be silent when deleting files, showing nothing as they are removed (default)
  -i --interactive     Ask for confirmation before deleting
                       Not compatible with --impl=native
  -I --no-interactive  Do not ask for confirmation before deleting

  --impl=<type>        Specify the implementation to use:
                       rimraf: choose the best option (default)
                       native: the built-in implementation in Node.js
                       manual: the platform-specific JS implementation
                       posix: the Posix JS implementation
                       windows: the Windows JS implementation (falls back to move-remove on ENOTEMPTY)
                       move-remove: a slow reliable Windows fallback

Implementation-specific options:
  --tmp=<path>        Temp file folder for 'move-remove' implementation
  --max-retries=<n>   maxRetries for 'native' and 'windows' implementations
  --retry-delay=<n>   retryDelay for 'native' implementation, default 100
  --backoff=<n>       Exponential backoff factor for retries (default: 1.2)

  10. Configure rimraf options

    main

    When calling rimraf or rimrafSync, you can pass an options object to customize behavior:

    • preserveRoot: Boolean. If false, allows recursive removal of the root directory. Defaults to true (not allowed).
    • glob: Boolean or object. If true, treats the path as a glob pattern. If an object, it accepts glob options.
    • filter: A method (path, direntOrStats) => boolean. Only removes entries where the filter returns a truthy value. Note: Using a filter prevents the use of Node's built-in fs.rm.
    • signal: An AbortSignal to cancel the removal process. Using a signal also prevents the use of Node's built-in fs.rm.
    • tmp: (Windows only) Temp folder for the "move then remove" fallback. Must be on the same physical device as the target.
    • maxRetries: (Windows and Native only) Max retry attempts for EBUSY, EMFILE, and ENFILE errors. Default 10 for Windows, 0 for Native.
    • backoff: (Windows only) Exponential backoff rate. Default 1.2.
    • maxBackoff: (Windows only) Maximum total backoff time in ms. Default 200.
    • retryDelay: (Native only) Linear backoff delay in ms. Default 100.

  12. Use the rimraf CLI

    main

    The rimraf command line tool allows for recursive deletion of files and folders from the terminal.

    rimraf <path> [<path> ...]

    Security Warning: Never pass untrusted user input to the rimraf CLI tool, as it can be used to delete arbitrary files or move files to unexpected locations via the --tmp option.