A customizable Node.js CLI tool designed to remove unnecessary directories from outdated projects.
Over time, projects accumulate unnecessary files and folders, especially large directories like node_modules that can take up significant disk space. When projects are no longer actively maintained or used, these directories become redundant, but you don't want to waste time on manually identifying and removing them.
nm-cleanup helps automate this process, saving you time and effort. It scans your directories, identifies unused or outdated project folders, and cleans up unnecessary files (like node_modules), freeing up valuable disk space.
The tool provides various options allowing to define what to clean up, which makes it suitable for a wide range of cleanup tasks beyond just node_modules.
💡 It's built with flexibility and automation in mind, so it's a great fit for both running manually and scheduled background execution, for example with cron.
- Recursively scan the specified root directory for project folders, as defined by the presence of project indicator files (e.g.,
package.json), defined with--project(-p) flag. - Check modification times for each project based on its contents and skipping directories matching
--exclude(-x) pattern. - Identify potential targets within found projects. Target is any file or directory matching the
--name(-n) pattern (e.g.,node_modules). - Print scan results categorizing projects into "fresh" and "old" with feedback on what was ignored, excluded, and most importantly, what targets were identified in each project.
- Prompt for confirmation before deleting the targets in the old projects. This step can be skipped with
--yes(-y) flag for automated usage. - Delete target directories only in those projects that haven't been modified for a certain threshold of time that can be adjusted with
--time(-t) (e.g.,30days).
Make sure you have Node.js installed on your machine. Then, install the tool globally:
npm install -g nm-cleanupnm-cleanup [rootDir] [options]or with alias:
nmc [rootDir] [options][rootDir]: The root directory containing all your projects. Defaults to the current directory (.).
Example
nm-cleanupor
nm-cleanup ~/projectsnm-cleanup provides a range of configurable options to allow flexible project cleanup. Below are detailed descriptions of each option and their usage.
Default
node_modules
Specifies a regex pattern to match directory names that should be removed.
Use this option when you want to clean up other types of folders besides node_modules.
Example
nm-cleanup --name 'dist|node_modules|\.cache'Default
30
Sets the threshold for how old a project should be (based on last modification time) before its directories are targeted for cleanup.
Use this option when you want to clean up projects that haven’t been modified for a specific period.
Example
nm-cleanup --time 60Default
^\.
Excludes directories from the filesystem scan, preventing nm-cleanup from even entering those directories. By default all hidden directories are excluded.
Use this option to improve performance when you have large or unnecessary directories that don’t need to be scanned, like backups, archives, or directories you know won't contain target folders.
Example
nm-cleanup --exclude '^logs|backups'Default
package.json
Defines the indicator files that mark a directory as a project. This allows nm-cleanup to treat any directory with these files as a project root.
Use this when working with projects that use different indicator files, such as Cargo.toml for Rust projects or composer.json for PHP projects.
Example
nm-cleanup --project composer.json gitlab-ci.yamlNo default
A list of paths to ignore during the cleanup process. This can include specific projects or nested directories.
Use this when you want to ensure that certain paths are never cleaned up.
Example
nm-cleanup --ignore projects/my-precious projects/special-projectDefault
false
When this option is enabled, nm-cleanup treats nested projects as independent entities for the purpose of modification time measurement. This means that the modification time of nested projects is considered separately from their parent projects. If a parent project is deemed outdated based on the modification time, its target folders will be cleaned up, while the nested projects, if still fresh, will be preserved.
Without this flag, the entire recursive structure of a project is managed as a single unit, meaning that all nested projects are taken into account when assessing whether the project as a whole should be cleaned up.
Use this option when you have a monorepo or a project structure with nested projects that you want to manage independently. This allows the cleanup of parent and sibling projects if only some of the nested siblings is not outdated.
Example
nm-cleanup --separate-nestedDefault
false
Skips the confirmation prompt and automatically proceeds with the cleanup.
Use this option when you want to run nm-cleanup in non-interactive environments, or life is to short to waste it on confirmation prompts.
Example
nm-cleanup --yesDefault
targets
Enables verbose output by category. When a category is enabled, all matched files and folders are printed. Otherwise, only the number of files in each category will be printed. Categories are: targets, ignored, excluded or none. By default only "targets" are enabled.
If no category options are provided (e.g., nmc -v), vervosity is enabled for all categories. If you don't want verbosity in any categories, set to none.
Example
nm-cleanup --verbose ignored targets
nm-cleanup --verboseDefault
false
Outputs all found projects, even if they don't have any targets to clean up.
Example
nm-cleanup --empty-targetsDefault
false
Performs a dry run of the cleanup process, showing what would be deleted without actually making any changes.
Use this to safely check what the tool does or test custom options configurations.
nm-cleanup --dry-runDisplays help information about the available commands and options.
Displays version.
Example
nm-cleanup --help