From cb2a30f455b6e1713d226bd3c89d9776d4a935e6 Mon Sep 17 00:00:00 2001 From: Lynnesbian Date: Wed, 7 Apr 2021 01:47:12 +1000 Subject: [PATCH] much better README --- README.md | 82 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 65 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 1e22002..6c1bbcf 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,78 @@ fif === -[![Crates.io](https://img.shields.io/crates/v/fif.svg?style=flat-square)](https://crates.io/crates/fif) -[![Crates.io](https://img.shields.io/crates/l/fif.svg?style=flat-square)](https://git.bune.city/lynnesbian/fif/src/branch/master/LICENSE) +[![Version](https://img.shields.io/crates/v/fif.svg?style=flat-square)](https://crates.io/crates/fif) +[![License](https://img.shields.io/crates/l/fif.svg?style=flat-square)](https://git.bune.city/lynnesbian/fif/src/branch/master/LICENSE) ![Minimum Supported Rust Version](https://img.shields.io/badge/msrv-1.43.0-orange?style=flat-square) [![CI Status](https://drone.bune.city/api/badges/lynnesbian/fif/status.svg?style=flat-square)](https://drone.bune.city/lynnesbian/fif) +[![unsafe forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/) A command-line tool for detecting and optionally correcting files with incorrect extensions. +fif recursively scans the given directory and outputs a shell script to fix the name of any files with incorrect +extensions. By default, fif will scan all non-hidden files in the given directory, and will ignore symlinks. + +As fif prints a shell script to stdout rather than acting on the files directly, you may wish to redirect its output to +a file, e.g. `fif ~/Documents > output.sh`. You can also pipe the output directly into your shell, e.g. +`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 -### Default backend +### Cargo ```bash cargo install --locked fif ``` -### 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 Linux, and infer on all other systems. +To update, simply re-run this command, or use a tool like +[cargo-update](https://github.com/nabijaczleweli/cargo-update). -xdg-mime should work on any Unixy system with [libmagic/file(1)](https://www.darwinsys.com/file/) installed, although -I've only tested it on Linux. infer should work on any system. +#### 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. + +`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. You can override the default backend for your system at compile time like so: ```bash # xdg-mime -cargo install --features=xdg-mime-backend +cargo install fif --features=xdg-mime-backend # infer -cargo install --features=infer-backend +cargo install fif --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: +```bash +cargo install fif --no-default-features ``` ## Usage See `fif --help` for more. -### The basics -The simplest way to use fif looks like this: +### Logging +By default, fif will log any warnings and/or errors encountered during execution. The verbosity of the logging can be +modified by the `RUST_LOG` to one of: `trace`, `debug`, `info`, `warn`, `error`. + +For example: + ```bash -fif -E images ~/Pictures +RUST_LOG=debug fif ~/Downloads ``` -This command will scan all of the files with extensions used by image files (.jpg, .png, etc) in your `~/Pictures` -directory. +### The basics +The simplest way to use fif looks like this: + +```bash +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: @@ -47,11 +80,26 @@ You can also manually specify a set of extensions to use: fif -e jpeg,jpg,zip,docx ~/Documents ``` -By default, fif will output a bash script that can be used to fix all the files it found with incorrect file extensions. +Or a set of extensions - for example, to scan files with image extensions (jpg, png, gif, bmp...): + +```bash +fif -E images ~/Pictures +``` + +For more information, see [the man page](https://git.bune.city/lynnesbian/fif/src/branch/master/doc/fif.1.txt) + +### Output +By default, fif will output a bash script (or PowerShell script on Windows) that can be used to fix all the files it +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 ``` -More coming soon! +You can also manually specify an output format to use: + +```bash +fif -O powershell ~/Documents > output.ps1 +```