From 518fb977b7e57e29f43dd45c8779894bb681fa9f Mon Sep 17 00:00:00 2001 From: Avril Date: Sat, 26 Nov 2022 12:32:45 +0000 Subject: [PATCH] Added README and license info MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fortune for enumerate-ordered's current commit: Future small blessing − 末小吉 --- Cargo.toml | 2 +- README.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+), 1 deletion(-) create mode 100644 README.md diff --git a/Cargo.toml b/Cargo.toml index b21458c..6e43b9b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,7 +4,7 @@ description = "Order files by their timestamps" authors=["Avril (Flanchan) "] version = "1.0.0" edition = "2021" - +license = "gpl3.0-or-later" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [profile.release] diff --git a/README.md b/README.md new file mode 100644 index 0000000..cc3c481 --- /dev/null +++ b/README.md @@ -0,0 +1,65 @@ +# `enumerate-ordered` - Order files by their timestamps +A shell utility to order input files by their modified, created, or accessed time. + +# Usage +The tool can take input paths from the command line or as lines from standard input if there are none provided on the command line. +It will output an ordered, newline-deliminated set of pathnames only after consuming its entire input. + +## Modes +* `enumerate-ordered [OPTIONS] [--] []` +** According to OPTIONS, given input file/directory paths `files...` (or, if empty, paths read from `stdin`), write them to `stdout` ordered by their metadata's timecodes +* `enumerate-ordered --help` +** Print this help message to `stderr`, then exit with code 0. + +## Options +* `-r`, `--recursive ` - Recursively sort input files, up to `` (set to 0 for infniite); if limit is not specified, recursion is infinite +* `-a`, `--atime` - Sort by atime +* `-c`, `--ctime` - Sort by ctime (default) +* `-m`, `--mtime` - Sort by mtime +* `-n`, `--reverse` - Print output in reverse +* `-p`, `--parallel cpus|` - Run tasks in parallel, with a max number of tasks being equal ``, or, if 0, to infinity (see `-P`), if 'cpus', to the number of logical CPU cores (default) +* `-P`, `--parallel 0` - Run tasks with unbounded parallelism, no limit to the number of walker tasks running at once (note: the physical thread pool will always be the same size regardless of these flags) +* `-1`, `--parallel 1` - Only let one directory be processed at once +* `-`, `--` - Stop parsing arguments, treat the rest as input paths + +## Env vars +*`RUST_LOG` - Control the logging (to stderr) level. +** "none" - No output. +** "error" - Errors only. +** "warn" - Warnings and above. +** "info" - Information and above. +** "debug" - Debug information and above. +** "trace" - All recorded information. + +# Example +``` shell +$ enumerate-ordered -Pnrm . # Recusrively and with unbounded parallel discovery print all files in the current directory in reverse order of their `atime` metadata fields. +$ ls -1 | grep -v '^\.' | enumerate-ordered -r # Recursively with bounded parallel discovery print all files in paths read from stdin (list of the current directory except any dotfiles/directories, e.g. '.git') in order of their `ctime` fields. +$ enumerate-ordered -1a .. . # With no parallel discovery or recursion print all files in the current and parent directory in order of their `atime` fields +``` + +# Building +You need `rust` and `cargo` installed to build the project. +Run: +``` shell +$ cargo build --release +``` +To create the optimised binary in `./target/release/enumerate-ordered`. + +## Build options +There are no compile-time flags (yet.) +To create debug builds, you can run: + +``` shell +$ cargo build +``` +To create the unoptimised binary in `./target/debug/enumerate-ordered`. + +Or, alternatively, for profiling: +``` shell +$ cargo build --profile prof +``` +Will create a non-stripped optimised binary in `./target/prof/enumerate-ordered`. + +# License +GPL'd with <3