added more info about installing/configuring fif to README
This commit is contained in:
parent
ca5773c167
commit
04574e5932
GPG key ID:
F0A184B5213D9F90
2 changed files with 61 additions and 25 deletions
|
|
@ -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
|
||||
|
|
|
|||
83
README.md
83
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).
|
||||
|
||||
<!-- links -->
|
||||
[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/
|
||||
Loading…
Reference in a new issue