README.md

   1 <!-- markdownlint-disable MD041 -->
   2 <!-- markdownlint-configure-file { "no-inline-html": { "allowed_elements": [div, h1, h4, p, i, img] } } -->
   3
   4 <div align="center">
   5   <h1>xdg-ninja</h1>
   6   <h4>
   7     Because you wouldn't let just anyone into your <i>$HOME</i>
   8   </h4>
   9 </div>
  10
  11 A shell script that checks your `$HOME` for unwanted files and directories.
  12
  13 <p align="center">
  14   <img src="https://s11.gifyu.com/images/68747470733a2f2f73382e67696679752e636f6d2f696d616765732f5065656b2d323032322d30352d31332d31362d30372e676966.gif" width="500" alt="xdg-ninja command output" />
  15 </p>
  16
  17 When `xdg-ninja` encounters a file or directory it knows about, it will tell you whether it's possible to move it to the appropriate location, and how to do it.
  18
  19 The configurations are from the [arch wiki page on XDG_BASE_DIR](https://wiki.archlinux.org/title/XDG_Base_Directory), [antidot](https://github.com/doron-cohen/antidot) (thanks to Scr0nch for writing a conversion tool), and crowdsourced by other users.
  20
  21 ## Installing
  22
  23 ### Manual Installation
  24
  25 Clone the repository, then run the [`./xdg-ninja.sh`](./xdg-ninja.sh) script.
  26
  27 ```sh
  28 git clone https://github.com/b3nj5m1n/xdg-ninja
  29 cd xdg-ninja
  30 ./xdg-ninja.sh
  31 ```
  32
  33 This will run every test in the default configuration.
  34
  35 ### [Nix](https://nixos.org)
  36
  37 Turn on [flakes](https://nixos.wiki/wiki/Flakes), then run the following command:
  38
  39 ```sh
  40 nix run github:b3nj5m1n/xdg-ninja
  41 ```
  42
  43 ### [Homebrew](https://brew.sh)
  44
  45 > [!NOTE]
  46 > Due to how `xdg-ninja` is developed, releases are not cut, so Homebrew ships a stale version, therefore you have to install and upgrade `xdg-ninja` from the git HEAD. ref: [#204](https://github.com/b3nj5m1n/xdg-ninja/issues/204)
  47 >
  48 > Homebrew will not upgrade `xdg-ninja` when running a generic `brew upgrade`, you must specifically upgrade `xdg-ninja` from the git HEAD, _see below_
  49
  50 Install:
  51
  52 ```sh
  53 brew install xdg-ninja --HEAD
  54 ```
  55
  56 Upgrade:
  57
  58 ```sh
  59 brew upgrade xdg-ninja --fetch-HEAD
  60 ```
  61
  62 ### Other Package Managers
  63
  64 `xdg-ninja` is avaliable in many other package managers.
  65
  66 The full list is available on the [repology page](https://repology.org/project/xdg-ninja/versions).
  67
  68 Follow the instructions for your package manager to install `xdg-ninja`.
  69
  70 ## Contributing
  71
  72 ### Dependencies
  73
  74 - Your favorite POSIX-compliant shell ([bash](https://repology.org/project/bash/packages), [zsh](https://repology.org/project/zsh/packages), [dash](https://repology.org/project/dash-shell/packages), etc.)
  75 - [jq](https://repology.org/project/jq/packages) for parsing the json files
  76 - [find](https://repology.org/project/findutils/versions)
  77
  78 #### Optional
  79
  80 - [glow](https://repology.org/project/glow/packages) for rendering Markdown in the terminal ([bat](https://repology.org/project/bat-cat/packages), [pygmentize](https://repology.org/project/pygments/versions) or [highlight](https://repology.org/project/highlight/packages) can be used as a fallback, but glow's output is clearer therefore glow is recommended)
  81
  82 ### Configuration
  83
  84 The configuration is done in the [`./programs/`](./programs/) directory, which should be located in the same working directory as the [`xdg-ninja.sh`](./xdg-ninja.sh) script. This can be overridden with the `XN_PROGRAMS_DIR` environment variable.
  85
  86 You define a program, and then a list of files and directories which that program ruthlessly puts into your `$HOME` directory.
  87
  88 For each file/directory, you specify if it can be (re)moved.
  89
  90 If this is the case, you also specify instructions on how to accomplish this in Markdown.
  91
  92 Files in this directory can have any name, but using the name of the program is recommended.
  93
  94 ### Automatically Generating Configuration
  95
  96 For x86_64 Linux systems, you can download the `xdgnj` binary from the [releases page](https://github.com/b3nj5m1n/xdg-ninja/releases).
  97
  98 Alternatively, you can build it from source using `cabal` or `stack`, use the nix flake or use the provided docker image.
  99
 100 > To be clear, this is just a tool that will help you automatically generate the config files, you still only need your shell to run the tests
 101
 102 #### Available commands
 103
 104 ```sh
 105 xdgnj add # Adds a new configuration
 106 xdgnj prev programs/FILE.json # Preview the configuration for a program
 107 xdgnj edit programs/FILE.json # Edit the configuration for a program
 108 xdgnj run # Mostly the same as running the shell script
 109 ```
 110
 111 #### Prebuilt Binaries
 112
 113 > [!IMPORTANT]
 114 > The binaries only run on x86_64 Linux systems.
 115
 116 ```sh
 117 curl -fsSL -o xdgnj https://github.com/b3nj5m1n/xdg-ninja/releases/latest/download/xdgnj
 118 chmod +x xdgnj
 119 ```
 120
 121 #### Building from source
 122
 123 You can use `cabal build` or `stack build`
 124
 125 #### Nix
 126
 127 ```sh
 128 nix run github:b3nj5m1n/xdg-ninja#xdgnj-bin ...
 129 ```
 130
 131 #### Docker
 132
 133 Use the provided dockerfile in [`./haskell/build/`](./haskell/build/).
 134
 135 ### Manually Creating Configuration
 136
 137 We're going to use `git` as an example.
 138
 139 By default, it puts the file `.gitconfig` into `$HOME`.
 140
 141 Luckily, the XDG spec is supported by git, so we can simply move the file to `$XDG_CONFIG_HOME/git/config`.
 142
 143 We can use that last sentence as our instructions. In this case, there are no newlines, so escaping this string for use in json is trivial, however, this is how you should generally approach it:
 144
 145 ```sh
 146 echo "Luckily, the XDG spec is supported by git, so we can simply move the file to _$XDG_CONFIG_HOME/git/config_." | jq -aRs .
 147 ```
 148
 149 Let's see what the output of this command looks like for something a little more sophisticated.
 150
 151 Here's an example file:
 152
 153 ```sh
 154 cat example.md
 155 ```
 156
 157 ```text
 158 Currently not fixable.
 159
 160 _(But you can probably just delete the dir)_
 161 ```
 162
 163 Here's what catting this file into `jq` produces:
 164
 165 ```sh
 166 cat example.md | jq -aRs .
 167 ```
 168
 169 ```text
 170 "Currently not fixable.\n\n_(But you can probably just delete the dir)_\n"
 171 ```
 172
 173 Now, we can assemble our final json file:
 174
 175 ```json
 176 {
 177     "name": "git",
 178     "files": [
 179         {
 180             "path": "$HOME/.gitconfig",
 181             "movable": true,
 182             "help": "Luckily, the XDG spec is supported by git, so we can simply move the file to _$XDG_CONFIG_HOME/git/config_.\n"
 183         }
 184     ]
 185 }
 186 ```
 187
 188 Saving this as `git.json` in the [`./programs/`](./programs/) directory will result in the script picking it up and checking the file.
 189
 190 If you've created a configuration for a file that isn't in the official repository yet, make sure to create a pull request so that other people can benefit from it as well.