del

Delete files and directories using globs

Similar to rimraf, but with a Promise API and support for multiple files and globbing. It also protects you against deleting the current working directory and above.

npm install del

import {deleteAsync} from 'del';

const deletedFilePaths = await deleteAsync(['temp/*.js', '!temp/unicorn.js']);
const deletedDirectoryPaths = await deleteAsync(['temp', 'public']);

console.log('Deleted files:\n', deletedFilePaths.join('\n'));
console.log('\n\n');
console.log('Deleted directories:\n', deletedDirectoryPaths.join('\n'));

A trailing ** matches everything inside a directory, but not the directory itself.

So this keeps goat.png and deletes everything else in public/assets, but leaves the public/assets directory behind, still holding goat.png:

deleteSync(['public/assets/**', '!public/assets/goat.png']);

Deleting a directory deletes everything inside it, except what is left out. A path that is left out, whether by a negated pattern or by the ignore, gitignore, ignoreFiles, or globalGitignore option, keeps the directories that hold it, and the rest of what is in them is deleted. This is so whether a pattern reaches inside the directory or only names it. So both of these keep public/assets/icons with goat.png inside it:

deleteSync(['public/assets/**', '!public/assets/icons/goat.png']);
deleteSync(['public/assets', '!public/assets/icons/goat.png']);

For each group of positive patterns, del looks inside the matched directories twice to find what was left out, with and without the exclusions that follow that group. A later positive pattern can bring back a directory and its contents. These scans always recurse and include dot files, regardless of deep, dot, or globstar, so they also walk excluded directories like a large node_modules. They only run when there is an exclusion.

To delete all subdirectories inside public/, you can do:

deleteSync(['public/*/']);

A pattern made up of nothing but negations matches nothing, as a negation only leaves paths out. To delete everything except some paths, say so with a positive pattern. This deletes the whole tree apart from keep.js and the dot files and directories at the top (pass dot: true to include those too). A negation only spares the exact path it names, so sub/keep.js goes with the rest:

deleteSync(['**', '!keep.js']);

You can pass expandNegationOnlyPatterns: true to have a pattern made up of nothing but negations match everything except them, like in globby.

Suggestions on how to improve this welcome!

Note that glob patterns can only contain forward-slashes, not backward-slashes. Windows file paths can use backward-slashes as long as the path does not contain any glob-like characters, otherwise use path.posix.join() instead of path.join().

Returns Promise<string[]> with the deleted paths.

If a deletion fails, no new fs.rm calls are started, and the promise rejects with the first error once the already-started fs.rm calls have settled. Node.js may continue deleting children of a directory after its recursive fs.rm call rejects.

Returns string[] with the deleted paths.

Type: string | string[]

See the supported glob patterns.

• Pattern examples with expected matches
• Quick globbing pattern overview

A pattern is a glob, so a filename that contains a glob metacharacter has to escape it. These are the two that fail silently, matching nothing at all rather than the name you meant:

deleteSync(['report (1).pdf']);
//=> []

deleteSync(['report [(]1[)].pdf']);
//=> ['/…/report (1).pdf']

deleteSync(['[test-abc]']);
//=> []

deleteSync(['[[]test-abc[]]']);
//=> ['/…/[test-abc]']

A character class is used rather than a backslash because on Windows del rewrites backslashes to forward-slashes, which would eat the escape. Only the patterns del takes for a path are rewritten, so report \(1\).p* keeps its backslashes while report \(1\).pdf does not. Off Windows nothing is rewritten and the backslash works.

The other metacharacters over-match rather than matching nothing: report {1}.pdf matches only its own name, report [1].pdf also matches report 1.pdf, and report *1*.pdf matches every report file with a 1 anywhere in it.

Type: object

You can specify any of the globby options in addition to the below options, except objectMode and stats, which return entries instead of paths. In contrast to the globby defaults, expandDirectories, onlyFiles, followSymbolicLinks, and expandNegationOnlyPatterns are false by default.

Type: boolean
Default: false

Allow deleting the current working directory and outside.

Type: boolean
Default: false

See what would be deleted.

import {deleteAsync} from 'del';

const deletedPaths = await deleteAsync(['temp/*.js'], {dryRun: true});

console.log('Files and directories that would be deleted:\n', deletedPaths.join('\n'));

Type: boolean
Default: false

Allow patterns to match files/folders that start with a period (.).

This option is passed through to fast-glob.

Note that an explicit dot in a portion of the pattern will always match dot files.

Example

directory/
├── .editorconfig
└── package.json

import {deleteSync} from 'del';

deleteSync('*', {dot: false, dryRun: true});
//=> ['/…/package.json']
deleteSync('*', {dot: true, dryRun: true});
//=> ['/…/.editorconfig', '/…/package.json']

Without dryRun the first call would delete package.json, so the second would only return .editorconfig.

Type: boolean
Default: false

Respect the ignore patterns in .gitignore files. This option is passed through to globby.

Note that it does not protect .git itself, only the files that .gitignore rules out. A broad pattern with dot: true will still match the repository metadata:

deleteSync('**/*', {gitignore: true, dot: true});
//=> `/…/.git`, `/…/.git/objects`, … are deleted

Add '**/.git' to ignore if that is not what you want.

The .gitignore files it reads are the ones inside cwd plus, when cwd is inside a Git repository, the ones from the repository root down. A .gitignore above cwd therefore applies too, and can leave out a file inside it that you asked to delete.

Type: number
Default: 256 for the deletions, os.cpus().length for the directory reads
Minimum: 1

Concurrency limit. deleteAsync applies it to the deletions and, through globby, to how many directories are read at once, so a low value also slows down finding the files. deleteSync deletes one path at a time and globby reads synchronously, so the option has no effect there.

The paths are ordered so that a directory is always removed after the paths inside it, but that order only holds as far as concurrency reaches. With followSymbolicLinks: true, a symlink that is the only route to its target can be unlinked before the paths below it are removed, which leaves them on disk while still reporting them as deleted. It leaves files behind rather than removing too much, and concurrency: 1 avoids it.

Type: string
Default: process.cwd()

The directory the patterns are relative to, and the boundary that del refuses to delete outside of without force. Only the process working directory and the directories above it are protected no matter what this is set to, so a cwd elsewhere moves the boundary with it.

import {deleteSync} from 'del';

// Deletes `dist` and everything in it, without touching anything above it.
deleteSync('dist', {cwd: '/var/www/app'});

Type: (progress: ProgressData) => void

Called after each file or directory is deleted, and once with no path when there is nothing to delete.

import {deleteAsync} from 'del';

await deleteAsync(patterns, {
	onProgress: progress => {
	// …
}});

{
	totalCount: number,
	deletedCount: number,
	percent: number,
	path?: string
}

• percent is a value between 0 and 1
• path is the absolute path of the deleted file or directory. It is not present when there is nothing to delete, which is the only time the report has no path.
• with the dryRun option, deletedCount and path describe what would have been deleted, since nothing is deleted at all

See del-cli for a CLI for this module and trash-cli for a safe version that is suitable for running by hand.

• make-dir - Make a directory and its parents if needed
• globby - User-friendly glob matching