Update README with examples and documentation

[hashgood] / README.md

diff --git a/README.md b/README.md
index 295200de50957e300012bbad6510515b2af9ecc5..c08c43ed174a61e567ff321457c2bdfcbe6a53fd 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,2 +1,49 @@
 # hashgood
-CLI tool for easily verifying a downloaded file's checksum
+A CLI tool for easily verifying a downloaded file's checksum.
+
+Wouldn't it be nice if your computer compared the hash for you?
+
+![](img/fail.png)
+![](img/maybe.png)
+
+Read the MD5, SHA1 or SHA256 hash from:
+
+* Command line argument
+* SHASUMS-style check files (`-c`)
+* Raw hash in a file/STDIN (`-c`)
+* The clipboard (`-p`)
+
+...or just run `hashgood` against the input and receive all three at once.
+
+This program arose from dissatisfaction with the [workarounds required for traditional tools](https://thomask.sdf.org/blog/2019/05/05/techniques-for-verifying-shasums-conveniently.html).
+
+## Compiling
+
+`hashgood` targets stable Rust. With a Rust toolchain installed, clone the repository and run:
+
+```
+cargo build --release
+```
+
+Take the compiled executable from `target/release/hashgood`.
+
+To include support for pasting from the clipboard with `-p`, specify the extra feature. Note that on Linux this requires several extra libraries: `libxcb1-dev libxcb-xfixes0-dev libxcb-shape0-dev libxcb-render0-dev`
+
+```
+cargo build --release --features paste
+```
+
+## Goals
+
+* Be forgiving and deliver what the user wants with a minimum of fuss. They just want to check this hash, damnit.
+* Don't let users be tricked - be explicit about checksum types and the sources of those checksums that are being compared.
+* As much cross-platform support as is practical.
+
+## Non-goals
+
+* Scriptability. This is an interactive tool.
+* Support for any unusual scenarios that could compromise smooth operation. (e.g., text mode, uncommon hash types)
+
+## Future ideas
+
+* Nominate a default (downloads) directory and auto-select the most recently created file in that directory as input.