-
Notifications
You must be signed in to change notification settings - Fork 146
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* fix: update `brew` install docs * chore: fix formatting and spelling * feat!: reformat everything and change verbage The entire README has been reformatted following the guidelines of `markdownlint` The verbage has been changed to be more clear and concise. The information has not been changed * chore: move manual install instructions to top Also add the commands to do so. * feat: add repology link for other package managers * fix: accidentally replaced italics with codeblock * chore: move `Avaliable Commands` section back up Also add documentation on how to download from releases
- Loading branch information
Showing
1 changed file
with
102 additions
and
39 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,127 +1,190 @@ | ||
| <div> | ||
| <h1 align="center">xdg-ninja</h1> | ||
| <h5 align="center">Because you wouldn't let just anyone into your <i>$HOME</i></h5> | ||
| <!-- markdownlint-disable MD041 --> | ||
| <!-- markdownlint-configure-file { "no-inline-html": { "allowed_elements": [div, h1, h4, p, i, img] } } --> | ||
|
|
||
| <div align="center"> | ||
| <h1>xdg-ninja</h1> | ||
| <h4> | ||
| Because you wouldn't let just anyone into your <i>$HOME</i> | ||
| </h4> | ||
| </div> | ||
|
|
||
| A shell script which checks your _$HOME_ for unwanted files and directories. | ||
| A shell script that checks your `$HOME` for unwanted files and directories. | ||
|
|
||
| <p align="center"> | ||
| <img src="https://s11.gifyu.com/images/68747470733a2f2f73382e67696679752e636f6d2f696d616765732f5065656b2d323032322d30352d31332d31362d30372e676966.gif" width="500"/> | ||
| <img src="https://s11.gifyu.com/images/68747470733a2f2f73382e67696679752e636f6d2f696d616765732f5065656b2d323032322d30352d31332d31362d30372e676966.gif" width="500" alt="xdg-ninja command output" /> | ||
| </p> | ||
|
|
||
| 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. | ||
| 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. | ||
|
|
||
| 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. | ||
| 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. | ||
|
|
||
| ## Running | ||
| ## Installing | ||
|
|
||
| ### Using nix | ||
| ### Manual Installation | ||
|
|
||
| Clone the repository, then run the [`./xdg-ninja.sh`](./xdg-ninja.sh) script. | ||
|
|
||
| ```sh | ||
| git clone https://github.com/b3nj5m1n/xdg-ninja | ||
| cd xdg-ninja | ||
| ./xdg-ninja.sh | ||
| ``` | ||
|
|
||
| This will run every test in the default configuration. | ||
|
|
||
| ### [Nix](https://nixos.org) | ||
|
|
||
| Turn on [flakes](https://nixos.wiki/wiki/Flakes), then run the following command: | ||
|
|
||
| If you're using [nix](https://nixos.org) and have flakes turned on, you can just run the following command: | ||
| ```sh | ||
| nix run github:b3nj5m1n/xdg-ninja | ||
| ``` | ||
|
|
||
| ### Cloning Manually | ||
| ### [Homebrew](https://brew.sh) | ||
|
|
||
| Clone the repository somewhere, then run the _./xdg-ninja.sh_ script. | ||
| > [!NOTE] | ||
| > 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) | ||
| > | ||
| > Homebrew will not upgrade `xdg-ninja` when running a generic `brew upgrade`, you must specifically upgrade `xdg-ninja` from the git HEAD, _see below_ | ||
| This will run every test in the default configuration. | ||
| Install: | ||
|
|
||
| ```sh | ||
| brew install xdg-ninja --HEAD | ||
| ``` | ||
|
|
||
| Upgrade: | ||
|
|
||
| ```sh | ||
| brew upgrade xdg-ninja --fetch-HEAD | ||
| ``` | ||
|
|
||
| ### Other Package Managers | ||
|
|
||
| `xdg-ninja` is avaliable in many other package managers. | ||
|
|
||
| ### Installing with Homebrew | ||
| The full list is available on the [repology page](https://repology.org/project/xdg-ninja/versions). | ||
|
|
||
| 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. | ||
| Follow the instructions for your package manager to install `xdg-ninja`. | ||
|
|
||
| ## Dependencies | ||
| ## Contributing | ||
|
|
||
| - 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), ...) | ||
| ### Dependencies | ||
|
|
||
| - 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.) | ||
| - [jq](https://repology.org/project/jq/packages) for parsing the json files | ||
| - [find](https://repology.org/project/findutils/versions) | ||
|
|
||
| ### Optional | ||
| #### Optional | ||
|
|
||
| - [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) | ||
| - [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) | ||
|
|
||
| ## Configuration | ||
| ### Configuration | ||
|
|
||
| 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. | ||
| 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. | ||
|
|
||
| You define a program, and then a list of files and directories which this program ruthlessly puts into your _$HOME_ directory. | ||
| You define a program, and then a list of files and directories which that program ruthlessly puts into your `$HOME` directory. | ||
|
|
||
| For each file/directory, you specify if it can be (re)moved. | ||
|
|
||
| If this is the case, you also specify instructions on how to accomplish this in Markdown. | ||
|
|
||
| Files in this directory can have any name, but using the name of the program is encouraged. | ||
| Files in this directory can have any name, but using the name of the program is recommended. | ||
|
|
||
| ### Automatically Generating Configuration | ||
|
|
||
| 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) | ||
| For x86_64 Linux systems, you can download the `xdgnj` binary from the [releases page](https://github.com/b3nj5m1n/xdg-ninja/releases). | ||
|
|
||
| Alternatively, you can build it from source using `cabal` or `stack`, use the nix flake or use the provided docker image. | ||
|
|
||
| > 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 | ||
| #### Available commands | ||
|
|
||
| Available commands: | ||
| ```sh | ||
| xdgnj add # Adds a new configuration | ||
| xdgnj prev programs/FILE.json # Preview the configuration for a program | ||
| xdgnj edit programs/FILE.json # Edit the configuration for a program | ||
| xdgnj run # Mostly the same as running the shell script | ||
| ``` | ||
|
|
||
| #### Using nix | ||
| #### Prebuilt Binaries | ||
|
|
||
| > [!IMPORTANT] | ||
| > The binaries only run on x86_64 Linux systems. | ||
| ```sh | ||
| curl -fsSL -o xdgnj https://github.com/b3nj5m1n/xdg-ninja/releases/latest/download/xdgnj | ||
| chmod +x xdgnj | ||
| ``` | ||
|
|
||
| #### Building from source | ||
|
|
||
| You can use `cabal build` or `stack build` | ||
|
|
||
| #### Nix | ||
|
|
||
| If you're using [nix](https://nixos.org) and have flakes turned on, you can just run the following command: | ||
| ```sh | ||
| nix run github:b3nj5m1n/xdg-ninja#xdgnj-bin ... | ||
| ``` | ||
|
|
||
| #### Building from scratch | ||
| #### Docker | ||
|
|
||
| You can use `cabal build`, `stack build`, or the provided dockerfile in _build/_. | ||
| Use the provided dockerfile in [`./haskell/build/`](./haskell/build/). | ||
|
|
||
| ### Manually | ||
| ### Manually Creating Configuration | ||
|
|
||
| We're going to use _git_ as an example. | ||
| We're going to use `git` as an example. | ||
|
|
||
| It puts the file _.gitconfig_ into _$HOME_. | ||
| By default, it puts the file `.gitconfig` into `$HOME`. | ||
|
|
||
| Luckily, the XDG spec is supported by git, so we can simply move the file to _XDG_CONFIG_HOME/git/config_. | ||
| Luckily, the XDG spec is supported by git, so we can simply move the file to `$XDG_CONFIG_HOME/git/config`. | ||
|
|
||
| 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: | ||
|
|
||
| ```sh | ||
| echo "Luckily, the XDG spec is supported by git, so we can simply move the file to _XDG_CONFIG_HOME/git/config_." | jq -aRs . | ||
| echo "Luckily, the XDG spec is supported by git, so we can simply move the file to _$XDG_CONFIG_HOME/git/config_." | jq -aRs . | ||
| ``` | ||
|
|
||
| Let's see what the output of this command looks like for something a little more sophisticated. | ||
|
|
||
| Here's an example file: | ||
|
|
||
| ```sh | ||
| cat example.md | ||
| ``` | ||
| ``` | ||
|
|
||
| ```text | ||
| Currently not fixable. | ||
| _(But you can probably just delete the dir)_ | ||
| ``` | ||
| Here's what catting this file to the _jq_ command produces: | ||
|
|
||
| Here's what catting this file into `jq` produces: | ||
|
|
||
| ```sh | ||
| cat example.md | jq -aRs . | ||
| ``` | ||
| ``` | ||
|
|
||
| ```text | ||
| "Currently not fixable.\n\n_(But you can probably just delete the dir)_\n" | ||
| ``` | ||
|
|
||
| Now, we can assemble our final json file: | ||
|
|
||
| ```json | ||
| { | ||
| "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" | ||
| "help": "Luckily, the XDG spec is supported by git, so we can simply move the file to _$XDG_CONFIG_HOME/git/config_.\n" | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| Saving this as _git.json_ in the _programs/_ directory will result in the script picking it up and checking the file. | ||
| Saving this as `git.json` in the [`./programs/`](./programs/) directory will result in the script picking it up and checking the file. | ||
|
|
||
| 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. |