readme

README.md

@@ -1,3 +1,94 @@
 # Galton
 
-Let your downloads into the right place
+*Let your downloads fall into the right place*
+
+Galton sorts your new downloads based on a set of rules.
+
+## Installation
+
+Pre-build releases can be downloaded from the
+[releases](https://codeberg.org/icewind/galton/releases) page.
+
+Alternatively you can build it yourself using either `nix build` or
+`cargo build`.
+
+## Usage
+
+```shell
+galton --config <config> watch <download directory>
+```
+
+You can also apply your rules to an existing file using
+
+```shell
+galton --config <config> file <path>
+```
+
+## Rules
+
+Each rule can have 3 different match options containing a regex:
+
+- `name`: the filename of the file
+- `url`\*: the source url of the file
+- `referrer`\*: the referrer of the file
+
+\*: See the "Url and referrer" section for more information and restrictions.
+
+And two action options:
+
+- `move`: directory to move the file into, will be created if necessary
+- `rename`: rename the file
+
+Action options can refer to capture groups from the match options and the file
+mtime to dynamically set the target directory and name.
+
+Multiple rule sections can be configured, the first matching rule will be used.
+
+### Examples
+
+Move a download based on the filename
+
+```toml
+[[rule]]
+name = ".+\\.(stl|3mf)" # note that we need to double the \\ for to escape regex
+move = "~/Printables"
+```
+
+Move a file based on where it's downloaded from.
+
+```toml
+[[rule]]
+referrer = "https://www.thingiverse.com/model/(?<model>.+)"
+move = "~/Printables/$model"
+```
+
+Rename a file when moving
+
+```toml
+[[rule]]
+name = "\\.(csv|CSV)"
+url = "https://www.paypal.com"
+move = "~/Downloads/Paypal Statements/$mtime.csv" # $mtime is set to the unix timestamp
+```
+
+### Url and referrer
+
+Galton uses the standard `user.xdg.origin.url` and `user.xdg.referrer.url`
+extended attributes to determine the download url and referrer.
+
+However browsers currently don't set the attributes on download files, firefox
+users can use [originfox](https://codeberg.org/icewind/originfox) as a
+workaround.
+
+## Lastest download symlink
+
+To make it easy to open the file you just downloaded, galton can be configured
+to automatically create a symlink to the new location of the file.
+
+```toml
+[watch]
+symlink = "~/Downloads/last"
+```
+
+Note that this symlink will only be set for files that match any of the
+configured rules.