The battle against cluttered home directories has found a new champion in xdg-ninja, a shell script designed to identify and help users clean up unwanted files and directories in their $HOME folder. This tool has sparked significant discussion within the developer community about file organization standards and the ongoing struggle to maintain clean user directories in Unix-like systems.
The Problem of Home Directory Pollution
For decades, applications on Unix-like systems have defaulted to storing configuration files directly in the user's home directory, typically as hidden dot files (files prefixed with a period). Over time, this practice leads to significant clutter as dozens or even hundreds of applications create their own configuration files and directories without any standardized structure. This historical approach has frustrated users who find their home directories becoming increasingly disorganized, with no clear separation between different types of application data.
This is one of the reasons I like Flatpak, it can force misbehaving apps to not pollute my home folder with their hidden .folders that never get cleaned up on removal and instead go in a managed directory where it belongs.
The XDG Base Directory Specification
The XDG Base Directory Specification was created by the freedesktop.org (formerly X Desktop Group) to address this exact problem. It defines a standard directory structure for application files, separating them into distinct categories: configuration files in $XDG_CONFIG_HOME (defaulting to ~/.config), data files in $XDG_DATA_HOME (defaulting to ~/.local/share), and cache files in $XDG_CACHE_HOME (defaulting to ~/.cache). This structured approach makes it easier to manage, back up, and clean application data.
Despite the specification being available for years, many applications still default to the old behavior of placing files directly in $HOME for backward compatibility or simply because developers haven't updated their code to follow the newer standard.
XDG-Ninja Installation Methods:
- Manual: Clone repository and run
./xdg-ninja.sh - Nix:
nix run github:b3nj5m1n/xdg-ninja - Homebrew: Available but ships stale version (requires manual upgrades)
- Various other package managers (see repology page)
Dependencies:
- POSIX-compliant shell (bash, zsh, dash, etc.)
- jq (for parsing JSON files)
- find
- Optional: glow (recommended), bat, pygmentize, or highlight for Markdown rendering
XDG Base Directory Default Locations:
- Configuration files:
$XDG_CONFIG_HOME(defaults to~/.config) - Data files:
$XDG_DATA_HOME(defaults to~/.local/share) - Cache files:
$XDG_CACHE_HOME(defaults to~/.cache)
How XDG-Ninja Works
XDG-ninja scans the user's home directory for files and directories that could be moved to follow the XDG Base Directory Specification. For each identified item, it provides information about whether the file can be moved and specific instructions on how to accomplish this. For example, the tool might detect a .gitconfig file in the home directory and advise the user that Git supports the XDG specification, allowing the configuration to be moved to ~/.config/git/config.
The tool is highly configurable, with program definitions stored in JSON files that specify which files to check for and how to handle them. Users can contribute new program definitions to help others clean up their directories as well.
Community Perspectives
The community discussion around XDG-ninja reveals diverse opinions about directory organization standards. While many users appreciate the more organized approach that the XDG specification brings, others express frustration with the implementation or transition process. Some users point out that tools like Flatpak already enforce proper directory isolation, while others debate whether environment variables or configuration files represent the better approach to application settings.
Interestingly, the conversation highlights how deeply personal file organization can be for technical users, with some expressing strong preferences about where and how their system stores configuration data. The discussion also reveals a generational divide between older Unix conventions and newer organizational standards.
Beyond Cleaning: A Philosophy of Organization
At its core, XDG-ninja represents more than just a cleaning tool—it embodies a philosophy about how user data should be organized on modern systems. By encouraging applications to follow a consistent standard, it aims to improve the user experience through better organization, easier backups, and cleaner home directories.
For users interested in trying XDG-ninja, the tool can be installed through various package managers or directly from its GitHub repository. While the transition to XDG-compliant applications continues gradually across the ecosystem, tools like XDG-ninja help users take control of their home directories in the meantime.
Reference: xdg-ninja: A shell script which checks your $HOME for unwanted files and directories