You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
enumerate-ordered/README.md

66 lines
2.9 KiB

# `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] [--] [<files...>]`
** 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 <limit>` - Recursively sort input files, up to `<limit>` (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|<max tasks>` - Run tasks in parallel, with a max number of tasks being equal `<max tasks>`, 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