README.md

   1 <div>
   2   <h1 align="center">xdg-ninja</h1>
   3   <h5 align="center">Because you wouldn't let just anyone into your <i>$HOME</i></h5>
   4 </div>
   5
   6 A shell script which checks your _$HOME_ for unwanted files and directories.
   7
   8 <p align="center">
   9   <img src="https://s11.gifyu.com/images/68747470733a2f2f73382e67696679752e636f6d2f696d616765732f5065656b2d323032322d30352d31332d31362d30372e676966.gif" width="500"/>
  10 </p>
  11
  12 When it encounters a file it knows about, it will tell you whether it's possible to move this file to an appropriate location, and how to do it.
  13
  14 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 contributed by other users.
  15
  16 ## Running
  17
  18 ### Using nix
  19
  20 If you're using [nix](https://nixos.org) and have flakes turned on, you can just run the following command:
  21 ```sh
  22 nix run github:b3nj5m1n/xdg-ninja
  23 ```
  24
  25 ### Cloning Manually
  26
  27 Clone the repository somewhere, then run the _./xdg-ninja.sh_ script.
  28
  29 This will run every test in the default configuration.
  30
  31 ### Installing with Homebrew
  32
  33 To install xdg-ninja with [Homebrew](https://brew.sh), run `brew install xdg-ninja` to install the script and all of its dependencies, then run the `xdg-ninja` command.
  34
  35 ## Dependencies
  36
  37 - 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), ...)
  38 - [jq](https://repology.org/project/jq/packages) for parsing the json files
  39
  40 ### Optional
  41
  42 - [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 fallback, but glow's output is clearer and therefore glow is recommended)
  43
  44 ## Configuration
  45
  46 The configuration is done in the _programs/_ directory, which should be located in the same working directory as the xdg-ninja.sh script. This can be overriden with the `XN_PROGRAMS_DIR` environment variable.
  47
  48 You define a program, and then a list of files and directories which this program ruthlessly puts into your _$HOME_ directory.
  49
  50 For each file/directory, you specify if it can be (re)moved.
  51
  52 If this is the case, you also specify instructions on how to accomplish this in Markdown.
  53
  54 Files in this directory can have any name, but using the name of the program is encouraged.
  55
  56 ### Automatically Generating Configuration
  57
  58 You can download the _xdgnj_ executable from the releases page. Alternatively, you can use the nix flake or build it from scratch using _cabal_, _stack_, or the provided docker image in _build/_. (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)
  59
  60 Available commands:
  61 ```sh
  62 xdgnj add # Adds a new configuration
  63 xdgnj prev programs/FILE.json # Preview the configuration for a program
  64 xdgnj edit programs/FILE.json # Edit the configuration for a program
  65 xdgnj run # Mostly the same as running the shell script
  66 ```
  67
  68 #### Using nix
  69
  70 If you're using [nix](https://nixos.org) and have flakes turned on, you can just run the following command:
  71 ```sh
  72 nix run github:b3nj5m1n/xdg-ninja#xdgnj-bin ...
  73 ```
  74
  75 #### Building from scratch
  76
  77 You can use `cabal build`, `stack build`, or the provided dockerfile in _build/_.
  78
  79 ### Manually
  80
  81 We're going to use _git_ as an example.
  82
  83 It puts the file _.gitconfig_ into _$HOME_.
  84
  85 Luckily, the XDG spec is supported by git, so we can simply move the file to _XDG_CONFIG_HOME/git/config_.
  86
  87 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:
  88 ```sh
  89 echo "Luckily, the XDG spec is supported by git, so we can simply move the file to _XDG_CONFIG_HOME/git/config_." | jq -aRs .
  90 ```
  91
  92 Let's see what the output of this command looks like for something a little more sophisticated.
  93 Here's an example file:
  94 ```sh
  95 cat example.md
  96 ```
  97 ```
  98 Currently not fixable.
  99
 100 _(But you can probably just delete the dir)_
 101 ```
 102 Here's what catting this file to the _jq_ command produces:
 103 ```sh
 104 cat example.md | jq -aRs .
 105 ```
 106 ```
 107 "Currently not fixable.\n\n_(But you can probably just delete the dir)_\n"
 108 ```
 109
 110 Now, we can assemble our final json file:
 111 ```json
 112 {
 113     "name": "git",
 114     "files": [
 115         {
 116             "path": "$HOME/.gitconfig",
 117             "movable": true,
 118             "help": "Luckily, the XDG spec is supported by git, so we can simply move the file to _XDG_CONFIG_HOME/git/config_.\n"
 119         }
 120     ]
 121 }
 122 ```
 123
 124 Saving this as _git.json_ in the _programs/_ directory will result in the script picking it up and checking the file.
 125
 126 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.