-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
f38a0b6
commit a8b416f
Showing
1 changed file
with
85 additions
and
11 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,39 +1,113 @@ | ||
# rush 🪶 | ||
|
||
**Rush** is a command-line utility that lets you run one command on many files using a simple command template syntax. | ||
**Rush** is a command-line utility that lets you run one command on many files using a simple command template syntax. For example, let's say you have a bunch of `.jpeg` files, and you really want them to be named `.jpg` instead. You can do | ||
|
||
## Examples | ||
```sh | ||
rush mv *.jpg '{{name}}.jpg' | ||
``` | ||
|
||
Change extensions on a bunch of files | ||
to accomplish this. If you want to instead convert them to PNGs and tag them with their last-modified dates, you can do | ||
|
||
```sh | ||
rush mv *.jpeg '{{name}}.jpg' | ||
rush convert *.jpg '{{mdate}}-{{name}}.png' | ||
``` | ||
|
||
Rename all PDF files to numbers | ||
When run, Rush first creates an output file name for each input file using the template string given (you'll find the full list of allowed parameters below). Then, the given command (`mv` or `convert` above) is run on each of the input-output pairs. In other words, running `rush cp *.pdf '{{name}}.{{mdate}}.pdf'` on a few files named `alpha.pdf`, `beta.pdf`, and `gamma.pdf` would run something like | ||
|
||
```sh | ||
cp alpha.pdf alpha.2021-04-29.pdf | ||
cp beta.pdf beta.2021-08-12.pdf | ||
cp gamma.pdf gamma.2022-05-04.pdf | ||
``` | ||
rush mv *.pdf '{{i}}.pdf' | ||
|
||
In this way, Rush makes doing one thing with many files pretty quick and painless. I originally made Rush to help me mass-rename and convert image files, but I've realized since then that this pattern is pretty universally useful. You _can_ do _some_ of the things Rush can do with a `for` loop in Bash, but I always forget the syntax, and it's much harder to get right. So most of the time, I reach for `rush`. | ||
|
||
## How do I use it? | ||
|
||
Typing `rush --help` gives us the help menu. If you'd rather learn by example, see the [examples](#examples). | ||
|
||
``` | ||
Rush lets you work on many files at once. | ||
Usage | ||
rush [cmd] [src-files] [rename-spec] [options] | ||
Add a prefix "secret" to all files, but don't delete originals | ||
Options | ||
--[h]elp Show this help message | ||
--stdin Receive source files list from STDIN | ||
--[d]ry-run Print all operations, but do not run them | ||
--[v]erbose Print all executed commands as they are run | ||
--version Print version information and exit | ||
--[f]orce Overwrite any conflicting files | ||
--debug Print CLI arguments for debugging then exit | ||
Template parameters | ||
path Full absolute path of the file | ||
e.g. "/home/me/image.jpg" | ||
dir Directory of the file | ||
e.g. "/home/me" | ||
fullname Entire file name, including extension | ||
e.g. "image.jpg" | ||
name File name, without the extension | ||
e.g. "image" | ||
ext Extension of the file (string after last '.', or | ||
empty string if there is no '.') | ||
e.g. "jpg" | ||
i Integer index of this file when the file list is | ||
sorted lexicographically | ||
e.g. "10" | ||
mtime Last-modified time of the file as a UNIX timestamp | ||
e.g. "1651654423" | ||
mdate Last-modified date of the file as an ISO date string | ||
e.g. "2022-05-04" | ||
len Size of the file in bytes | ||
e.g. "4094" | ||
``` | ||
rush cp * 'secret-{{fullname}}' | ||
|
||
### Examples | ||
|
||
Change extensions on a bunch of files. | ||
|
||
```sh | ||
rush mv *.jpeg '{{name}}.jpg' | ||
``` | ||
|
||
Add last-modified times to photos and put them in folders by dates | ||
Rename all PDF files to numbers in increasing order. | ||
|
||
```sh | ||
rush mv *.pdf '{{i}}.pdf' | ||
``` | ||
rush mv * '{{mdate}}/{{name}}-{{mtime}}.{{ext}}' | ||
|
||
Add a prefix "secret" to all files, but don't delete the originals. | ||
|
||
```sh | ||
rush cp * 'secret-{{fullname}}' | ||
``` | ||
|
||
Convert all PNGs to JPGs using ImageMagick "convert" | ||
Organize files by their last-modified dates into folders and add their last-modified timestamps to their names. (For this to work, the folders must exist beforehand.) | ||
|
||
```sh | ||
rush mv * '{{mdate}}/{{name}}-{{mtime}}.{{ext}}' | ||
``` | ||
|
||
Convert all PNGs to JPGs using [ImageMagick "convert"](https://imagemagick.org/script/convert.php). | ||
|
||
```sh | ||
rush convert *.png '{{name}}.jpg' | ||
``` | ||
|
||
## Install | ||
|
||
If you have [Oak](https://oaklang.org) installed, you can build from source (see below). Otherwise, I provide pre-built binaries for macOS and Linux (both x86) on the [releases page](https://github.com/thesephist/rush/releases). Just drop those into your `$PATH` and you should be good to go. | ||
|
||
## Build and development | ||
|
||
Rush is built with my [Oak programming language](https://oaklang.org), and I manage build tasks with a Makefile. | ||
|
||
- `make` or `make build` builds a version of Rush at `./rush` | ||
- `make install` installs Rush to `/usr/local/bin`, in case that's where you like to keep your bins | ||
- `make fmt` or `make f` formats all Oak source files tracked by Git | ||
|
||
## Why's it called _Rush_? | ||
|
||
It's short, doesn't conflict with any commonly-used CLIs, and felt like a fast... word to me. |