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://s8.gifyu.com/images/Peek-2022-05-13-16-07.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 Currently, a subset of the [arch wiki page on XDG_BASE_DIR](https://wiki.archlinux.org/title/XDG_Base_Directory) is implemented as configurations.
  15
  16 ## Running
  17
  18 Clone the repository somewhere, then run the _./xdg-ninja.sh_ script.
  19
  20 This will run every test in the default configuration.
  21
  22 ## Dependencies
  23
  24 - [bash](https://repology.org/project/bash/packages), obviously
  25 - [jq](https://repology.org/project/jq/packages) for parsing the json files
  26
  27 ### Optional
  28
  29 - [glow](https://repology.org/project/glow/packages) for rendering markdown in the terminal
  30 - [cabal](https://repology.org/project/cabal/packages) for compiling the helper program for creating configurations
  31
  32 ## Configuration
  33
  34 The configuration is done in the _programs/_ directory.
  35
  36 You define a program, and then a list of files and directories which this program ruthlessly puts into your _$HOME_ directory.
  37
  38 For each file/directory, you specify if it can be (re)moved.
  39
  40 If this is the case, you also specify instructions on how to accomplish this in markdown.
  41
  42 Files in this directory can have any name, but using the name of the program is encouraged.
  43
  44 ### Automatically Generating Configuration
  45
  46 You need _haskell_ and _cabal_ installed. (To be clear, this is just for a tool that will help you automatically generate the config files, you still only need bash to run the tests)
  47
  48 Run the following command:
  49 ```bash
  50 cabal build
  51 ```
  52
  53 You should now have a binary which you can run. You'll find it in somewhere in _dist-newstyle/build_, for example in _dist-newstyle/build/x86_64-linux/ghc-9.0.2/add-program-0.1.0.0/x/add-program/build/add-program/add-program_.
  54
  55 Execute this binary in this directory. It will guide you through the process.
  56
  57 ### Manually
  58
  59 We're going to use _git_ as an example.
  60
  61 It puts the file _.gitconfig_ into _$HOME.
  62
  63 Luckily, the XDG spec is supported by git, so we can simply move the file to _XDG_CONFIG_HOME/git/config_.
  64
  65 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:
  66 ```bash
  67 echo "Luckily, the XDG spec is supported by git, so we can simply move the file to _XDG_CONFIG_HOME/git/config_." | jq -aRs .
  68 ```
  69
  70 Let's see what the output of this command looks like for something a little more sophisticated.
  71 Here's an example file:
  72 ```bash
  73 cat example.md
  74 ```
  75 ```
  76 Currently not fixable.
  77
  78 _(But you can probably just delete the dir)_
  79 ```
  80 Here's what catting this file to the _jq_ command produces:
  81 ```bash
  82 cat example.md | jq -aRs .
  83 ```
  84 ```
  85 "Currently not fixable.\n\n_(But you can probably just delete the dir)_\n"
  86 ```
  87
  88 Now, we can assemble our final json file:
  89 ```json
  90 {
  91     "name": "git",
  92     "files": [
  93         {
  94             "path": "$HOME/.gitconfig",
  95             "movable": true,
  96             "help": "Luckily, the XDG spec is supported by git, so we can simply move the file to _XDG_CONFIG_HOME/git/config_.\n"
  97         }
  98     ]
  99 }
 100 ```
 101
 102 Saving this as _git.json_ in the _programs/_ directory will result in the script picking it up and checking the file.
 103
 104 If you've created a configuration for a file that isn't in the offical repository yet, make sure to create a pull request so that other people can benefit from it as well.