constUP Garbage Cleaner

Table of Contents

• Support this tool
• Description
  • Quick info
  • Preview of commands
• Why?
• Prerequisites and compatibility
• Installation and updating
  • Method 1: Download a release
  • Method 2: Cloning this repository
  • Updating
  • Optional: Add constUP Garbage Cleaner to PATH
• Basic use
  • Cleaning by using default set of rules
  • Cleaning by using custom set of rules
  • Dry run
    • Detailed dry run
• More documentation
• Support
• License

Support this tool

Description

Simple, easy to use and configurable garbage cleaner for Windows. Deletes files, directories and registry entries. Written in PowerShell 7 with simple JSON configuration. Tested on PowerShell 7.4.

Quick info

• A PowerShell script which can be run from terminal or automated to be run by your own scripts

• Configurable with a simple JSON file

• It can clean files, directories and registry values

• It has a built-in cleanup list, but supports your own custom cleanup lists as well

  • The default cleanup list does not require administrative privileges

  • Each entry in the default cleanup list is carefully reviewed by consulting official documentation to verify that it is safe to delete

  • Custom cleanup lists which you can expand whenever you need, without having to wait for the update or submit a feature request

  • Custom cleanup lists which you can easily share with anyone or have them on multiple devices

• Granular cleaning using filters like application, category,…​

• Built-in helpful instructions on how to prevent further garbage creation

• No tracking, no telemetry, no pinging home, completely free and open source

Preview of commands

Here is a preview of some of the commands. If you already have experience with running applications from terminal, you might get a general idea about this application from these commands. Of course, each command (and more) is covered in this documentation:

pwsh .\constup-garbage-cleaner.ps1 -clean
pwsh .\constup-garbage-cleaner.ps1 -clean -cleanupListFile /path/to/your/cleanup-list.json
pwsh .\constup-garbage-cleaner.ps1 -dryRun
pwsh .\constup-garbage-cleaner.ps1 -dryRun -detailed
pwsh .\constup-garbage-cleaner.ps1 -listActive
pwsh .\constup-garbage-cleaner.ps1 -listApplications
pwsh .\constup-garbage-cleaner.ps1 -listCategories
pwsh .\constup-garbage-cleaner.ps1 -clean -applications "Firefox,Chrome"
pwsh .\constup-garbage-cleaner.ps1 -clean -types "file,registry value"
pwsh .\constup-garbage-cleaner.ps1 -clean -customCategories "your category,some other category"
pwsh .\constup-garbage-cleaner.ps1 -clean -applications "Firefox,Chrome" -entityCategories "log,crash log"

Why?

There is a number of tools available on the market, both free and commercial, for cleaning garbage files and registry entries. However, each of them has one or more of the following downsides:

• Free versions have limited features compared to their paid ones.

• They are deleting more than they should. This is especially true when deleting browser data with these tools. Deleting too much have different effects, depending on the tool: from logging you out of websites and destroying your sessions to even messing up CSS of web pages. (Note: these are real world examples).

• They are not deleting what they should. Many tools and applications are not covered by other cleaners. For example, did you know that WebStorm can produce a Java crash log of 3+ GB in your Windows user directory? That’s the very first rule in the default cleanup list of constUP Garbage Cleaner, and is the primary inspiration for building this tool.

• You can not expand their set of cleaning rules (easily). You’ve just found out that some application on your computer is creating garbage not covered by your cleaning rules? Just open your cleanup-list.json and add the rule to clean it in a matter of minutes (even seconds, if you type fast enough).

• They are filled with bloatware which has nothing to do with cleaning the system.

• Many of them outright lie about the amount of space saved by running their software. This is especially noticeable in antivirus software with cleaning features.

• They are "pinging home" - collecting your information and uploading it to their servers. Especially those which have "software updater tools", which are harvesting the list of all software which you have installed on your computer, determining their versions and uploading that information to their servers.

• They are closed source and have access to all files on your computer and all registry entries.

• You can not (easily) process garbage which you or applications which you have written produce. For example, if you are creating 3D renders and have a lot of temporary throwaway render samples, you can define cleaning rules to clean them up with constUP Garbage Cleaner. Or, if you are a programmer and your application produces logs which you need only temporarily, you can define cleaning rules for those logs as well.

• Even if defining custom rules is possible, it is not easy to transfer them to another machine, let alone share them with the community and improve cleaning performance for many users.

• They do not support multiple cleaning configurations and rule sets.

Prerequisites and compatibility

• Microsoft Windows 11 (it also should work on Windows 10, but that’s not tested)

• Microsoft PowerShell 7

  • Installation instructions: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows

Installation and updating

Method 1: Download a release

Download a release from https://github.com/constup/garbage-cleaner-powershell/releases, and extract it to your desired location.

To update, just download a newer release.

Method 2: Cloning this repository

git clone git@github.com:constup/garbage-cleaner-powershell.git

or:

git clone https://github.com/constup/garbage-cleaner-powershell.git

or with GitHub CLI:

gh repo clone constup/garbage-cleaner-powershell

Updating

To update, open terminal and enter the directory where constUP Garbage Cleaner is located, then run:

git fetch origin master
git pull origin master

Important

Please note that the default cleanup list bundled with constUP Garbage Cleaner will be updated along with the application. If you have yor own set of cleaning rules, make sure to store them in your own custom cleanup list file.

Optional: Add constUP Garbage Cleaner to PATH

To run constUP Garbage Cleaner from any location, you can add it to your system’s PATH environment variable.

A handy PowerShell script is provided in this repository. Just run add-to-path.ps1, and it will add constUP Garbage Cleaner’s directory to your user’s PATH environment variable. Don’t worry about running this script more than once - it only adds to PATH if the directory is not already there. You can run it with:

pwsh .\add-to-path.ps1

Basic use

This describes the basic use of the constUP Garbage Cleaner. Basic use only checks if the cleanup rule is active or not.

Important

constUP Garbage Cleaner has more advanced usage options which are covered in Advanced use.

Cleaning by using default set of rules

The following command will perform the cleaning using the default cleaning rules provided in cleanup-list.json.

pwsh .\constup-garbage-cleaner.ps1 -clean

Cleaning by using custom set of rules

If you are not happy with the default set of cleaning rules, you can use the following command to run the cleaner with your own set of rules. The cleaning rules are covered in Cleanup list file and listing available applications, categories,…​.

pwsh .\constup-garbage-cleaner.ps1 -clean -cleanupListFile /path/to/your/cleanup-list.json

Important

All constUP Garbage Cleaner commands have an option to either use the default cleanup list or your custom one. To make this documentation shorter, we will not mention instructions for the custom cleanup list anymore - but it’s available, just like in the example above. Just use the -cleanupListFile option and set the path to your own cleanup list.

Dry run

You can dry run constUP Garbage Cleaner with:

pwsh .\constup-garbage-cleaner.ps1 -dryRun

This will detect garbage on your system, but will not delete it. This option is useful when you want to roughly preview what is going to be deleted.

Detailed dry run

To get more detailed information about the garbage on your system without cleaning it, run:

pwsh .\constup-garbage-cleaner.ps1 -dryRun -detailed

This will:

• List all garbage with their locations and sizes.

• Each cleanup rule can have information on how to prevent garbage creation (relevant to that particular rule). Detailed dry run will show this information, but only for garbage which was found on your system.

More documentation

The following documentation is also available:

• Dry run (with garbage creation prevention instructions and cleanup list configuration file error detection)

• Cleanup list file and listing available applications, categories,…​

  • Categories

• Advanced use (including cleaning by property filters, for example: application, category,…​)

• Planned features - what’s coming up next

• Testing - Unit testing with Pester

• Contributing - guidelines for software contribution, feature requests and populating the cleanup list

Support

If you like this tool or find it useful, consider buying me a nice cup of coffee. Coffee fuels open source.

License

Mozilla Public License 2.0 (also available on Mozilla’s website at: MPL 2.0)