diff --git a/API.md b/API.md index 584331f2..79ec1bc5 100644 --- a/API.md +++ b/API.md @@ -1,8 +1,12 @@ # NPKill API -This document does not include all project documentation at this stage. It brings together the basic concepts. +This document describes the public core API of npkill and its fundamental concepts. For more details see the project interfaces. +> [!WARNING] +> +> Some things may change in future patches until the API is 100% stable. Please leave me your feedback if you use it! + - [NPKill API](#npkill-api) - [Interface: `Npkill`](#interface-npkill) - [`startScan$(rootPath, options?)`](#startscanrootpath-options) diff --git a/README.md b/README.md index 1e4872ce..710a8154 100644 --- a/README.md +++ b/README.md @@ -8,148 +8,185 @@ NPM

-### Easily find and **remove** old and heavy **node_modules** folders :sparkles: +### Easily find and **remove** old and heavy **node_modules**. And everything else you don’t need.

npkill demo GIF

-This tool allows you to list any _node_modules_ directories in your system, as well as the space they take up. You can then select which ones you want to erase to free up space. Yay! - -## i18n - -We're making an effort to internationalize the Npkill docs. Here's a list of the available translations: - -- [Español](./README.es.md) -- [Indonesian](./README.id.md) -- [Português](./README.pt.md) -- [Turkish](./README.tr.md) +**Your system remembers everything. npkill helps you forget.** +This tool scans your system for heavy and unnecessary development directories. +It shows you what is taking up space, when you stopped using it, why it’s there, and lets you remove it in seconds. ## Table of Contents - [Features](#features) -- [Installation](#installation) - [Usage](#usage) - [Multi-Select Mode](#multi-select-mode) + - [Search](#search) + - [Profiles](#profiles) + - [.npkillrc](#npkillrc) - [Options](#options) - [Examples](#examples) - [JSON Output](#json-output) - [Set Up Locally](#setup-locally) -- [API](#API) -- [Roadmap](#roadmap) -- [Known bugs](#known-bugs) +- [API](#api) - [Contributing](#contributing) - [Buy us a coffee](#donations) - [License](#license) -# :heavy_check_mark: Features +# ✨ Features -- **Clear space:** Get rid of old and dusty _node_modules_ cluttering up your machine. +- **Beyond node_modules** + Started with `node_modules`, extended to entire development environments. + Remove build artifacts, caches, temp files, and other heavy leftovers using built-in or custom profiles. -- **Last Workspace Usage**: Check when was the last time you modified a file in the workspace (indicated in the **last_mod** column). +- **Profiles-first scanning** + Scan your system using predefined profiles for Node.js, Python, Rust, game engines, and more. Or create your own to match your workflow. -- **Very fast:** NPKILL is written in TypeScript, but searches are performed at a low level, improving performance greatly. +- **Effortless by default** + A clean and responsive TUI designed to stay out of your way. + See everything clearly, make decisions fast, and clean with confidence. -- **Easy to use:** Say goodbye to lengthy commands. Using npkill is as simple as reading a list of your node_modules, and pressing Del to get rid of them. Could it be any easier? ;) +- **Workspace awareness** + See at a glance when you last worked in that workspace and find out if it's an active project or a long-forgotten one. -- **Minified:** It barely has any dependencies. +- **Built for speed** + npkill is written in TypeScript, but searches are performed at a low level, delivering blazing-fast performance and near-instant responsiveness. - + -# :cloud: Installation +# :clipboard: Usage -You don't really need to install it to use it! Simply use the following command: ```bash $ npx npkill ``` -Or if for some reason you really want to install it: - -```bash -$ npm i -g npkill -# Unix users may need to run the command with sudo. Go carefully -``` +By default, npkill will start searching for node-related development directories from the directory where you ran it, using the built-in **node** profile. -> NPKILL does not support node +> [!NOTE] +> **TL;DR:** You can learn everything as you go because the TUI explains itself. -# :clipboard: Usage +You can navigate between them with ↓ ↑, and use Space or Del to delete the selected folder. -```bash -$ npx npkill -# or just npkill if installed globally -``` +You can view more information about the result by pressing → and go back by pressing ←. -By default, npkill will scan for node_modules starting at the path where `npkill` command is executed. +If necessary, you can open the parent directory with o. -Move between the listed folders with ↓ ↑, and use Space or Del to delete the selected folder. -You can also use j and k to move between the results. +You can see more navigation keys in the built-in **quick reference panel**. -You can open the directory where the selected result is placed by pressing o. +> [!WARNING] +> Some applications installed on the system need their node_modules directory to work and deleting them may break them. npkill will try to identify them and highlight them by displaying a :warning: to be careful. -To exit, Q or Ctrl + c if you're brave. +> [!IMPORTANT] +> npkill **find** candidates for deletion but does not decide what is safe for you. +> +> - Results are based on common conventions. +> - Whether a folder is safe to delete always depends on the scope. +> +> Always review results before deleting anything. -**Important!** Some applications installed on the system need their node_modules directory to work and deleting them may break them. NPKILL will highlight them by displaying a :warning: to be careful. + -## Multi-Select Mode +## :ballot_box_with_check: Multi-Select mode This mode allows you to select and delete multiple folders at once, making it more efficient when cleaning up many directories. -### Entering Multi-Select Mode +### Entering Multi-Select mode -Press T to toggle multi-select mode. When active, you'll see a selection counter and additional instructions at the top of the results. +Press **t** to toggle multi-select mode. When active, you'll see a selection counter and additional instructions at the top of the results. ### Controls - **Space**: Toggle selection of the current folder. -- **V**: Start/end range selection mode. -- **A**: Toggle select/unselect all folders. -- **Enter**: Delete all selected folders. -- **T**: Unselect all and back to normal mode. +- **v**: Start/end range selection mode. +- **a**: Toggle select/unselect all folders. +- **Enter**: Delete all selected folders at once. +- **t**: Unselect all and back to normal mode. ### Range Selection -After pressing V to enter range selection mode: +After pressing **v** to enter range selection mode: -- Move the cursor with arrow keys, j/k, Home/End, or page up/down +- Move the cursor with arrow keys, **j**/**k**, **Home**/**End**, or **PgUp**/**PgDn**. - All folders between the starting position and current cursor position will be selected/deselected -- Press V again to exit range selection mode +- Press **Enter** to delete all selected folders together. +- Press **v** again to exit range selection mode. + + + +## :mag: Search + +> _Divide and conquer._ + +You can filter the results displayed by pressing **/**. What you type will then appear in the yellow bar at the top. + +Press **Enter** to browse through the filtered results. + +To clear the filter, press **/** again and delete the term. + +This feature can be especially useful for narrowing down results by path without restarting `npkill`. + +> [!NOTE] +> The search supports regular expressions. + + + +## :card_index: Profiles + +**Profiles** are a set of _targets_ that represent a **development ecosystem**. + +You can list the available profiles with `npkill --profiles` and use them as follows: `npkill --profiles node,python`. + +Profiles and their targets may change between versions of npkill. So if this is important to you, I recommend creating your own with `.npkillrc`. + + + +## :gear: .npkillrc + +The `.npkillrc` file allows you to define the default behavior of npkill without having to pass parameters every time. It is also where you can define your own custom profiles. + +You can read all the details in the [`.npkillrc documentation`](./docs/npkillrc.md). -## Options - -| ARGUMENT | DESCRIPTION | -| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| -p, --profiles | Allows you to select the [profile](./docs/profiles.md) (set of targets) to use. If no option is specified, the available ones will be listed _(**node** by default)_. | -| --config | Path to a custom .npkillrc configuration file. By default, npkill looks first for `./.npkillrc` and then for `~/.npkillrc`. | -| -d, --directory | Set the directory from which to begin searching. By default, starting-point is . | -| -D, --delete-all | Automatically delete all folders that are found. Suggested to be used together with `-x`. | -| -e, --hide-errors | Hide errors if any | -| -E, --exclude | Exclude directories from search (directory list must be inside double quotes "", each directory separated by ',' ) Example: "ignore1, ignore2" | -| -f, --full | Start searching from the home of the user (example: "/home/user" in linux) | -| --size-unit | Set the unit for displaying folder sizes. _(Available: **auto**, mb, gb)_. With auto, sizes < 1024MB are shown in MB (rounded), larger sizes in GB (with decimals). | -| -h, --help, ? | Show help page | -| -nu, --no-check-update | Don't check for updates on startup | -| -s, --sort | Sort results by: `size`, `path` or `age` | -| -t, --targets | Disable profiles feature and specify the name of the directories you want to search for. You can define multiple targets separating with comma. Ej. `-t node_modules,.cache`. | -| -x, --exclude-sensitive | Exclude sensitive directories. | -| -y | Avoid displaying a warning when executing --delete-all. | -| --dry-run | It does not delete anything (will simulate it with a random delay). | -| --json | Output results in JSON format at the end of the scan. Useful for automation and scripting. | -| --json-stream | Output results in streaming JSON format (one JSON object per line as results are found). Useful for real-time processing. | -| -v, --version | Show npkill version | +## :wrench: Options + +| ARGUMENT | DESCRIPTION | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| -p, --profiles | Allows you to select the [profile](./docs/profiles.md) (set of targets) to use. If no option is specified, the available ones will be listed _(**node** by default)_. | +| --config | Path to a custom .npkillrc configuration file. By default, npkill looks first for `./.npkillrc` and then for `~/.npkillrc`. | +| -d, --directory | Set the directory from which to begin searching. By default, starting-point is . | +| -D, --delete-all | Automatically delete all folders that are found. Suggested to be used together with `-x`. | +| -e, --hide-errors | Hide errors if any | +| -E, --exclude | Exclude directories from search. Each directory separated by ','. By default, [some directories](https://github.com/voidcosmos/npkill/blob/main/src/core/constants/global-ignored.constants.ts) are ignored. | +| -f, --full | Start searching from the home of the user (example: "/home/user" in linux) | +| --size-unit | Set the unit for displaying folder sizes. _(Available: **auto**, mb, gb)_. With auto, sizes < 1024MB are shown in MB (rounded), larger sizes in GB (with decimals). | +| -h, --help, ? | Show help page | +| -nu, --no-check-update | Don't check for updates on startup | +| -s, --sort | Sort results by: `size`, `path` or `age` | +| -t, --targets | Disable profiles feature and specify the name of the directories you want to search for. You can define multiple targets separating with comma. Ej. `-t node_modules,.cache`. | +| -x, --exclude-sensitive | Exclude sensitive directories. | +| -y | Avoid displaying a warning when executing --delete-all. | +| --dry-run | It does not delete anything (will simulate it with a random delay). | +| --json | Output results in JSON format at the end of the scan. Useful for automation and scripting. | +| --json-stream | Output results in streaming JSON format (one JSON object per line as results are found). Useful for real-time processing. | +| --no-size | Skip size calculation. Useful for faster scanning and deletion when space info is not needed. | +| --no-age | Skip age (last modification time) calculation. | +| --no-stats | Skip both size and age calculation. Shortcut for `--no-size --no-age`. | +| -v, --version | Show npkill version | -## Examples +## :bulb: Examples -- Search **node_modules** directories in your _projects_ directory: +- Search in your _projects_ directory: ```bash npkill -d ~/projects @@ -159,54 +196,42 @@ cd ~/projects npkill ``` -- List directories named "dist" and show errors if any occur: - -```bash -npkill --target dist -e -``` - -- List **node_modules** in your _projects_ directory, excluding the ones in _progress_ and _ignore-this_ directories: - -```bash -npkill -d 'projects' --exclude "progress, ignore-this" -``` - -- Automatically delete all node_modules that have sneaked into your backups: +- Clean Node.js and Python development leftovers (`node_modules`, `__pycache__`, `.cache`, `.venv`, etc.): ```bash -npkill -d ~/backups/ --delete-all +npkill --profiles node,python ``` -- Get results in JSON format for automation or further processing: +- I only want clean `node_modules` like in the old times: ```bash -npkill --json > results.json +npkill -t node_modules ``` -- Stream results in real-time as JSON (useful for monitoring or piping to other tools): +- List **node_modules** in your _projects_ directory, excluding the ones in _progress_ and _ignore-this_ directories: ```bash -npkill --json-stream | jq '.' +npkill -d 'projects' --exclude "progress, ignore-this" ``` -- Save only successful results to a file, ignoring errors: +- Automatically delete all node-related leftovers that have sneaked into your backups: ```bash -npkill --json-stream 2>/dev/null | jq -s '.' > clean-results.json +npkill -d ~/backups/ --delete-all ``` -## JSON Output +## :floppy_disk: JSON Output -Npkill supports JSON output formats for automation and integration with other tools: +npkill supports JSON output formats for automation and integration with other tools: - **`--json`**: Output all results as a single JSON object at the end of the scan - **`--json-stream`**: Output each result as a separate JSON object in real-time For detailed documentation, examples, and TypeScript interfaces, see [JSON Output Documentation](./docs/json-output.md). -**Quick Examples:** +### Quick Examples ```bash # Get all results as JSON @@ -231,7 +256,7 @@ git clone https://github.com/voidcosmos/npkill.git cd npkill # -- Install dependencies -npm install +npm ci # -- And run! npm run start @@ -241,43 +266,13 @@ npm run start npm run start -- -f -e ``` - + # :bookmark_tabs: API The api allows you to interact with npkill from node to create your own implementations in your scripts (automations, for example). -You can check the basic API [here](./API.md) or on the web (comming soon). - - - -# :crystal_ball: Roadmap - -- [x] Release 0.1.0 ! -- [x] Improve code - - [x] Improve performance - - [ ] Improve performance even more! -- [x] Sort results by size and path -- [x] Allow the search for other types of directories (targets) -- [ ] Reduce dependencies to be a more minimalist module -- [ ] Allow to filter by directories that have not been used in a period of time -- [ ] Create option for displaying directories in tree format -- [x] Add some menus -- [x] Add log service -- [ ] Periodic and automatic cleaning (?) - - - -# :bug: Known bugs :bug: - -- Sometimes, CLI is blocked while folder is deleting. -- Sorting, especially by routes, can slow down the terminal when there are many results at the same time. -- Sometimes, size calculations are higher than they should be. -- (SOLVED) Performance issues when searching from high level directories (like / in linux). -- (SOLVED) Sometimes text collapses when updating the cli. -- (SOLVED) Analyzing the size of the directories takes longer than it should. - -> If you find any bugs, don't hesitate and open an issue :) +You can check the basic API [here](./API.md) or on the web. @@ -297,15 +292,9 @@ We will continue to do things anyway, but donations are one of the many ways to Open Collective donate button -### Thanks!! - -## A huge thank you to our backers :heart: - - - --- -### Crypto alternative +## Crypto alternative - btc: 1ML2DihUoFTqhoQnrWy4WLxKbVYkUXpMAX - bch: 1HVpaicQL5jWKkbChgPf6cvkH8nyktVnVk diff --git a/docs/npkillrc.md b/docs/npkillrc.md index 3a068bad..94fd557f 100644 --- a/docs/npkillrc.md +++ b/docs/npkillrc.md @@ -40,7 +40,7 @@ npkill --config /path/to/your/config.json ```json { "rootDir": "/home/user/projects", - "exclude": [".git", "important-project", "production-app"], + "exclude": ["important-project", "production-app"], "sortBy": "size", "sizeUnit": "auto", "excludeSensitiveResults": true, @@ -80,12 +80,12 @@ Absolute path from which the search will begin. ### exclude **Type:** `string[]` -**Default:** `[".git"]` +**Default:** `[]` Array of directory names to exclude from search. Npkill will skip these directories and their subdirectories. ```json -"exclude": [".git", "production-project", "node_modules/.cache"] +"exclude": ["production-project", "node_modules/.cache"] ``` ### sortBy diff --git a/docs/profiles.md b/docs/profiles.md index e8366b54..cf5bee6f 100644 --- a/docs/profiles.md +++ b/docs/profiles.md @@ -1,27 +1,44 @@ # Profiles -This document defines built-in profiles for npkill. A profile is a named preset of "safe-to-delete" directories for a given ecosystem. +This document describes the built-in profiles shipped with npkill. -While these directories are **generally safe to delete**, it all depends on their context. Therefore, it is important to verify the result shown before deleting it. However, we have tried to maintain a conservative list. +A **profile** is a curated set of directory names commonly associated with +rebuildable artifacts (such as caches, dependencies, or build outputs) within a given ecosystem. -- Profiles are opt-in via `--profiles` (comma-separated). Example: `--profiles node,python`. -- Only directory base names are matched (the last path segment) (more advanced heuristics will be implemented in the future). -- All targets below are rebuildable caches, dependencies, or compiled outputs. So doesnt should have any problem deleting it. But before delete, peek if is secure to remove for your case. +These profiles are provided as a **starting point**, not as an authoritative or exhaustive definition of what is safe to delete. -Default behavior +> [!WARNING] +> +> - Deletion safety always depends on project context. +> - npkill matches directory names only (the last path segment). It does not inspect contents or project semantics. +> - Some directories listed here may contain valuable data depending on your workflow. +> +> **Always review results before deleting anything.** +> When in doubt, prefer creating your own custom profiles tailored to your environment. -- By default (no `--profiles`), npkill use the `node` profile. +## How profiles work -Special profile: all +- Profiles are opt-in via `--profiles` (comma-separated). + Example: `--profiles node,python` +- Only directory base names are matched. +- Built-in profiles aim to be conservative, but cannot cover every edge case. -- `all` includes every target listed in all profiles below. Use with care if you want a full clean sweep. +## Default behavior -## node (default) +- When no `--profiles` option is provided, npkill uses the `node` profile by default. + +## Special profile: `all` + +- The `all` profile includes every target from all built-in profiles. +- This option is intentionally broad and should be used with extra care. + +## Built-in profiles + +### node (default) - `node_modules`: Node.js project dependencies. Deleting forces a full reinstallation. Regenerated by running `npm install`, `yarn`, or `pnpm install`. - `.npm`: npm's package cache. Deleting may slow down the next install. Regenerated automatically by npm on subsequent installs. - `.pnpm-store`: pnpm's global content-addressable store. Deleting removes all shared packages. Regenerated by pnpm on subsequent installs. -- `.yarn/cache`: Yarn v2+ local project cache. Deleting requires re-downloading packages. Regenerated by `yarn install`. - `.next`: Next.js build and cache directory. Deleting clears build artifacts and cache. Regenerated on the next `next dev` or `next build`. - `.nuxt`: Nuxt.js build output directory. Deleting removes the generated application. Regenerated by running `nuxt build`. - `.angular`: Angular CLI cache and metadata. Deleting is safe and may resolve caching issues. Regenerated by the Angular CLI during the next build or serve command. @@ -45,7 +62,7 @@ Special profile: all - `.stylelintcache`: Stylelint's cache for linted files. Deleting forces a full re-lint. Regenerated by Stylelint when run with the `--cache` flag. - `deno_cache`: Deno's cache for modules. Deleting is safe. Regenerated when Deno modules are next fetched. -## python +### python - `__pycache__`: Python bytecode files. Deleting is safe as they are regenerated by Python automatically. - `.pytest_cache`: pytest's cache for test results and metadata. Deleting may slow down the next test run. Regenerated automatically by pytest. @@ -59,7 +76,7 @@ Special profile: all - `.venv`: Python virtual environment. Deleting removes all installed packages and the isolated environment. Regenerated by creating a new virtual environment (e.g., `python -m venv .venv`). - `venv`: Same as `.venv`. Deleting removes the virtual environment. Regenerated similarly. -## data-science +### data-science - `.ipynb_checkpoints`: Jupyter Notebook's auto-save checkpoints. Deleting removes recovery points for notebooks. Regenerated automatically by Jupyter. - `__pycache__`: Python bytecode files. Deleting is safe. Regenerated automatically by Python. @@ -68,62 +85,62 @@ Special profile: all - `.dvc`: Data Version Control (DVC) cache and metadata. Deleting can lead to data loss if not properly managed. Regenerated by DVC commands like `dvc repro`. - `.mlruns`: MLflow experiment tracking logs. Deleting removes experiment history. Regenerated when you run new MLflow experiments. -## java +### java - `target`: Maven's build output directory. Deleting removes all compiled code, packages, and artifacts. Regenerated by running `mvn package` or other Maven build commands. - `.gradle`: Gradle's cache and wrapper files within a project. Deleting may slow down the next build. Regenerated automatically by Gradle. - `out`: Default output directory for some IDEs like IntelliJ IDEA. Deleting removes compiled classes. Regenerated on the next build. - Warning: `out` is a generic folder name in various ecosystems. -## android +### android - `.cxx`: Android NDK build cache. Deleting may slow down native builds. Regenerated by the Android Gradle plugin during the next build. - `externalNativeBuild`: External NDK build artifacts. Deleting removes intermediate native build files. Regenerated on the next native build. -## swift +### swift - `DerivedData`: Xcode's build artifacts, indexes, and cache. Deleting is a common troubleshooting step and clears the build cache. Regenerated by Xcode on the next build. - `.swiftpm`: Swift Package Manager's cache and build data. Deleting removes local package caches and build artifacts. Regenerated on the next `swift build` or resolve. -## dotnet +### dotnet - `obj`: Intermediate object files from the build process. Deleting forces a full recompile. Regenerated by the .NET compiler (e.g., `dotnet build`). - `TestResults`: Test output and reports. Deleting removes historical test data. Regenerated by running tests (e.g., `dotnet test`). - `.vs`: Visual Studio's local workspace data, including user-specific settings and cache. Deleting is generally safe. Regenerated when you open the solution in Visual Studio. -## rust +### rust - `target`: Cargo's build output directory. Deleting removes all compiled artifacts. Regenerated by running `cargo build`. -## ruby +### ruby - `.bundle`: Bundler's settings and cache for the project. Deleting is safe. Regenerated by `bundle install`. -## elixir +### elixir - `_build`: Mix's build output directory. Deleting removes compiled artifacts. Regenerated by `mix compile`. - `deps`: Project dependencies. Deleting requires re-fetching all dependencies. Regenerated by `mix deps.get`. - Warning: `deps/` is a generic name that may appear in non-Elixir projects too. - `cover`: Test coverage reports. Deleting removes historical coverage data. Regenerated by running tests with coverage enabled. -## haskell +### haskell - `dist-newstyle`: Cabal's build output and cache. Deleting removes compiled files. Regenerated by `cabal build`. - `.stack-work`: Stack's build cache and artifacts. Deleting removes compiled files and intermediate data. Regenerated by `stack build`. -## scala +### scala - `.bloop`: Bloop build server's metadata and configuration. Deleting may require re-importing the project in your IDE. Regenerated by Bloop. - `.metals`: Metals IDE's cache and build data. Deleting forces a re-index of the project. Regenerated when you open the project in a Metals-enabled editor. - `target`: sbt's build output directory. Deleting removes compiled code and artifacts. Regenerated by sbt build commands. -## cpp +### cpp - `CMakeFiles`: CMake's intermediate build files. Deleting forces CMake to regenerate the build environment. Regenerated by running `cmake`. - `cmake-build-debug`: CLion or CMake's debug build output. Deleting removes debug binaries. Regenerated on the next debug build. - `cmake-build-release`: CLion or CMake's release build output. Deleting removes release binaries. Regenerated on the next release build. -## unity +### unity - `Library`: Unity's cache of imported assets and metadata. Deleting is safe but forces a full re-import of all project assets, which can be time-consuming. Regenerated when Unity opens the project. - Warning: On macOS, this can match the critical `~/Library` system folder. @@ -131,19 +148,19 @@ Special profile: all - `Obj`: Intermediate object files from the build process. Deleting forces a full recompile. Regenerated on the next build. - Warning: Generic name; may appear in unrelated toolchains. -## unreal +### unreal - `Intermediate`: Intermediate build files. Deleting is safe and forces a regeneration of these files. Regenerated by the Unreal Engine build system. - Warning: Generic name; ensure it’s an Unreal project context. - `DerivedDataCache`: Cache for derived asset data. Deleting forces assets to be re-cooked. Regenerated on demand by the engine. - `Binaries`: Compiled binaries and libraries. Deleting removes executable files. Regenerated by the build system. -## godot +### godot - `.import`: Godot's cache of imported assets. Deleting forces a re-import of all assets. Regenerated when the Godot editor is opened. - `.godot`: Godot's project cache and metadata. Deleting is generally safe. Regenerated by the Godot editor. -## infra +### infra - `.serverless`: Serverless Framework's deployment artifacts. Deleting removes the packaged service. Regenerated on the next `serverless package` or `deploy`. - `.vercel`: Vercel's local project data and deployment cache. Deleting is safe for local development. Regenerated by the Vercel CLI.