From 04574e59320379258a3385c56b3377c55aacbd4d Mon Sep 17 00:00:00 2001 From: Lynnesbian Date: Mon, 10 May 2021 09:44:39 +1000 Subject: [PATCH] added more info about installing/configuring fif to README --- CHANGELOG.md | 3 +- README.md | 83 +++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 61 insertions(+), 25 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 99e8446..0a9799c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ Dates are given in YYYY-MM-DD format. - Added JSON output support via `-o json` #### Other - `videos` is now an alias for `video` +- More extensive README documentation ### v0.3.0 (2021-04-28) #### Features @@ -71,7 +72,7 @@ Dates are given in YYYY-MM-DD format. (files without extensions are still skipped unless the -S flag is used) #### Bugfixes - Fixed compilation on big endian 32-bit architectures (see - [here]https://github.com/bodil/smartstring/blob/v0.2.6/src/config.rs#L101-L103 for why that was a problem in the first + [here](https://github.com/bodil/smartstring/blob/v0.2.6/src/config.rs#L101-L103) for why that was a problem in the first place) - Fixed broken tests for the [`infer`] backend #### Other diff --git a/README.md b/README.md index 8caa64f..02f0ed1 100644 --- a/README.md +++ b/README.md @@ -27,41 +27,58 @@ a file, e.g. `fif ~/Documents > output.sh`. You can also pipe the output directl `fif ~/Documents | bash`, although this is not recommended - you should look over fif's output and verify for yourself that it's not doing anything that will give you a headache before running it. -## Installation -### Cargo +## Features +- :white_check_mark: Cross platform +- :white_check_mark: Multi-threaded +- :white_check_mark: Configurable + +## Building +fif can be built, installed, and tested with [Cargo], as with most rust programs: ```bash +git clone https://gitlab.com/Lynnesbian/fif/ +cd fif +# run tests (optional) +cargo test --locked +# build fif with its default feature set +cargo build --locked --release +``` +The `--locked` flag ensures that Cargo uses the dependency versions specified in [the lock +file](https://gitlab.com/Lynnesbian/fif/-/blob/master/Cargo.lock), and the `--release` flag builds fif with release +optimisations enabled -- this takes longer, but produces a much faster binary. + +### Installing +```bash +# install the fif crate (to ~/.cargo/bin or %USERPROFILE%\.cargo\bin by default) cargo install --locked fif ``` -To update, simply re-run this command, or use a tool like [cargo-update -](https://github.com/nabijaczleweli/cargo-update). +To update, simply re-run the `install` command, or use a tool like [cargo-update +](https://github.com/nabijaczleweli/cargo-update), which can update crates installed via `cargo install`. -#### Other backends -`fif` supports using [`infer`](https://crates.io/crates/infer) or [`xdg-mime`](https://crates.io/crates/xdg-mime) as its -backend for looking up file types. By default, xdg-mime will be used on -[*nix systems](https://en.wikipedia.org/wiki/Unix-like) (Linux, macOS, *BSD, etc.), and infer on all other systems. +### Cargo Features +fif supports using [`infer`] or [`xdg-mime`] as its backend for looking up file types. By default, xdg-mime will be +used on [*nix systems](https://en.wikipedia.org/wiki/Unix-like) (Linux, macOS, *BSD, etc.), and infer on all other +systems. -`xdg-mime` should work on any *nix system with [libmagic/file(1)](https://www.darwinsys.com/file/) installed, although -I've only tested it on Linux and FreeBSD. `infer` should work on any system. +`xdg-mime` should work on any *nix system with the [Shared MIME Info] library installed (consult your package +manager), although I've only tested it on Linux and FreeBSD. `infer` should work on any system. You can override the default backend for your system at compile time like so: ```bash # xdg-mime -cargo install fif --features=xdg-mime-backend +cargo install fif --locked --features=xdg-mime-backend # infer -cargo install fif --features=infer-backend +cargo install fif --locked --features=infer-backend ``` -Of the supported backends, `xdg-mime` by far supports the most file types, as it uses the excellent [Shared MIME -Info](https://gitlab.freedesktop.org/xdg/shared-mime-info/) database, whereas `infer` uses its own baked-in database. -However, `infer` is also faster to load, if only by a few dozen milliseconds, and has no external dependencies. - -#### Multithreading -It is also possible to disable multithreading by installing without default features: +It is also possible to get a more minimal build by installing without default features: ```bash -cargo install fif --no-default-features +cargo install fif --locked --no-default-features ``` +This will disable some non-essential but nice to have features, like multi-threading support. + +For more info on fif's compile-time features, see [the wiki](https://gitlab.com/Lynnesbian/fif/-/wikis/Cargo-Features). ## Usage See `fif --help` for more. @@ -75,16 +92,25 @@ fif ~/Downloads This command will scan all non-hidden files in your `~/Downloads` directory. -You can also manually specify a set of extensions to use: +The `-e` and `-E` flags can be used to specify individual extensions and sets of extensions to scan, respectively: ```bash +# only scan files with the extensions .jpeg, .jpg, .zip, and .docx fif -e jpeg,jpg,zip,docx ~/Documents +# only scan files with "image extensions" - .jpg, .png, .gif, .webp... +fif -E images ~/Pictures +# scan .zip files, videos, and audio +fif -e zip -E videos,audio ~/Downloads ``` -Or a set of extensions - for example, to scan files with image extensions (jpg, png, gif, bmp...): - +Both `-e` and `-E` have equivalent `-x` and `-X` flags that exclude the given extensions rather than including them: ```bash -fif -E images ~/Pictures +# scan everything except filenames ending in .zip +fif -x zip ~/Downloads +# scan all files with image extensions, but not .jpg and .jpeg files +fif -x jpg,jpeg -E images ~/Pictures +# scan everything except text and system files +fif -X text,system ~/.local/share ``` ### Output @@ -94,7 +120,7 @@ found with incorrect file extensions. You might find it useful to output this script to a file (rather than to stdout): ```bash -fif -E images ~/Pictures > output.sh +fif ~/Documents > output.sh ``` You can also manually specify an output format to use: @@ -143,3 +169,12 @@ The five logging levels are used as follows: | info | Information pertaining to fif's status | The provided directory was scanned without issue, and no files are in need of renaming | | debug | Debug information - usually not important to end users | The list of extensions fif will consider | | trace | Trace info - usually not important to end users | "Found 15 items to check", "Scan successful", etc. | + +For a more comprehensive explanation of all of fif's parameters and how to use them, run `fif --help` (or `fif -h` for +a more concise overview). + + +[Cargo]: https://doc.rust-lang.org/cargo/ +[`xdg-mime`]: https://crates.io/crates/xdg-mime +[`infer`]: https://crates.io/crates/infer +[Shared MIME Info]: https://gitlab.freedesktop.org/xdg/shared-mime-info/ \ No newline at end of file