xdg-ninja

You can install xdg-ninja using several methods depending on your environment:

Manual Installation

Clone the repository and run the shell script directly:

git clone https://github.com/b3nj5m1n/xdg-ninja
cd xdg-ninja
./xdg-ninja.sh

Nix

If you have Nix flakes enabled, run:

nix run github:b3nj5m1n/xdg-ninja

Homebrew

Note: Homebrew ships a stale version because releases are not cut. You must install and upgrade from the git HEAD.

To install:

brew install xdg-ninja --HEAD

To upgrade:

brew upgrade xdg-ninja --fetch-HEAD

Other Package Managers

xdg-ninja is available on many other package managers. Check the Repology page for a full list.

The xdgnj binary is a tool designed to help automatically generate configuration files. Note: This binary only runs on x86_64 Linux systems.

Installation (x86_64 Linux)

curl -fsSL -o xdgnj https://github.com/b3nj5m1n/xdg-ninja/releases/latest/download/xdgnj
chmod +x xdgnj

Available Commands

• xdgnj add: Adds a new configuration.
• xdgnj prev programs/FILE.json: Preview the configuration for a specific program.
• xdgnj edit programs/FILE.json: Edit the configuration for a specific program.
• xdgnj run: Runs the tool (similar to running the main shell script).

Configuration is managed via JSON files located in the ./programs/ directory (relative to the xdg-ninja.sh script). You can override this location by setting the XN_PROGRAMS_DIR environment variable.

Each JSON file defines a program and a list of files/directories it places in $HOME. For each entry, you specify if it is movable and provide Markdown help text explaining how to move it to an XDG-compliant location.

Configuration Schema Example

To add a program (e.g., git), create a file named git.json in the ./programs/ directory with the following structure:

{
    "name": "git",
    "files": [
        {
            "path": "$HOME/.gitconfig",
            "movable": true,
            "help": "Luckily, the XDG spec is supported by git, so we can simply move the file to _$XDG_CONFIG_HOME/git/config_.\n"
        }
    ]
}

To run xdg-ninja, you need the following dependencies:

Required:

• A POSIX-compliant shell (e.g., bash, zsh, dash)
• jq (for parsing JSON files)
• find (from findutils)

Optional (Recommended for better UI):

• glow (for rendering Markdown in the terminal). Fallbacks like bat, pygmentize, or highlight are supported but glow provides clearer output.

If you need to point xdg-ninja to a custom location for its programs information, set the XN_PROGRAMS_DIR environment variable.

Default search paths are programs/ or ../share/xdg-ninja/programs/.

Control the output verbosity and filtering of xdg-ninja using the following flags:

• -v, --no-skip-ok: Verbose mode. Displays messages for all files checked, including those that are already correctly placed.
• --skip-ok: (Default behavior) Suppresses output for files that do not exist.
• --skip-unsupported: Suppresses output for files that do not have available fixes/recommendations.