1 files changed, 49 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..03c77df
--- /dev/null
+++ b/README.md
@@ -0,0 +1,49 @@
+# bulk_rename
+
+Renames every file in a directory, either to names read from a list file
+(one name per line, matched in sorted order) or sequentially via a
+`sprintf`-style pattern.
+
+## Usage
+
+```
+bulk-rename [options] [DIRECTORY]
+```
+
+By default, operates on the current directory and reads target names from
+`fileNames.txt` in the parent directory.
+
+```
+-l, --list FILE       File with one target name per line
+                       (default: fileNames.txt in the parent of DIRECTORY)
+-p, --pattern PATTERN  sprintf pattern for sequential renaming instead of
+                        a list, e.g. 'wallpaper-%04d' - the original file
+                        extension is kept automatically
+-s, --start N          Starting number for --pattern (default: 1)
+-n, --dry-run           Show planned renames without doing them
+-f, --force             Overwrite existing files at the target name
+-h, --help              Print this menu
+```
+
+### Examples
+
+Rename every file in the current directory to sequential wallpaper names,
+starting at 1, previewing first:
+
+```
+bulk-rename --dry-run --pattern "wallpaper-%04d" ~/pics/wallpaper
+bulk-rename --pattern "wallpaper-%04d" ~/pics/wallpaper
+```
+
+Rename from an explicit list instead of the default `../fileNames.txt`:
+
+```
+bulk-rename --list ~/episode-titles.txt ~/vids/some-show
+```
+
+## Building and installing locally
+
+```sh
+gem build bulk_rename.gemspec
+sudo gem install ./bulk_rename-*.gem
+```