IIUC, based on skimming some of the code, this seems to be for people who want to layout their home directory according to the conventions that the XDG group suggested [1], well into the history of Unix-y systems.
For example, a given tool, `foo`, might've originally created a `~/.foo/` directory, which `foo` still supports for backward compatibility, but `foo` now prefers XDG convention `~/.config/foo/`. `xdg-ninja` can inform you of that, and help you move the directory.
For another example, tool `bar` might still default to config file `~/.barrc`, but `xdg-ninja` might advise you to move it to XDG-like `~/.config/bar/rc`, and to set `bar`'s `BARRC` environment variable to point to that, even though `bar` doesn't use XDG conventions directly.
[1] https://specifications.freedesktop.org/basedir-spec/latest/
Unfortunately, conventions and suggestions only sometimes work in software development. There will always be developers who ignore or actively fight the conventions because it's important to them to do everything their way. This is usually the reason behind why we still have Windows applications trying to install themselves under the root C:\ directory and macOS applications that ship with an unnecessary installer rather than using the conventional "drag the app into the Applications folder."
So while my `~` is not "clean" in the sense that all my config files are in `~/.config`, it is "clean" in the sense that all files in `~` are there for a reason (i.e., `~` is not polluted by the old config/cache of uninstalled packages).
The script should have a --without-env option or similar.
This is the crap responsible for poluting $HOME. If the user does not configure anything, just use global defaults.
First of all, writing state and configuration files in the home directory, without any well thought out structure, has been a common practice since UNIX existed, XDG did not even exist then.
Precisely because this lazy practice causes all sorts of problems, the cross-desktop group (XDG) came up with a standard called the "base directory specification"[1] which proposes to divide applications files into configuration, data, caches and are supposed to be stored in subdirectories named after the application in $XDG_CONFIG_HOME ($HOME/.config if unsed), $XDG_DATA_HOME ($HOME/.local/share if unset), $XDG_CACHE_HOME ($HOME/.cache if unset), respectively.
[1]: https://specifications.freedesktop.org/basedir-spec/latest/
I think people who wrote software used $HOME for dotfiles way before XDG even existed.
> If the user does not configure anything, just use global defaults.
And if he does, where do you put the dotfiles? $HOME? XDG defines an cleaner hierarchy.
A config file always belongs in ~/.config/PROGRAM. It never belongs in ~/.local/share/PROGRAM.
Data files (e.g. icons) belong in ~/.local/share/PROGRAM.
User-specific state (e.g. window positions) belongs in ~/.local/state/PROGRAM.
Executables belong in ~/.local/bin/.
Cached files (which may be deleted any time for space) belong in ~/.cache.
Source: https://specifications.freedesktop.org/basedir-spec/latest/
> Why not just have a single ~/.dotfiles or something (if hidden files in ~/ is somehow a problem that needs to be solved)?
I believe that the answer is that certain of those directories make sense to share across different hosts (e.g. your laptop and desktop) and others don’t.
Also; Some of those directories make sense to flag for backup in your favorite backup software (personal settings, data files, etc), where others (cache) make sense to not waste drive space on backing up.