Skip to content

Commit

Permalink
Update version and documentation link
Browse files Browse the repository at this point in the history
  • Loading branch information
@ayoisaiah
ayoisaiah committed Apr 26, 2021
1 parent 52ea561 commit b4d27a8
Show file tree
Hide file tree
Showing 2 changed files with 8 additions and 366 deletions.
370 changes: 6 additions & 364 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
- F2 helps you organise your filesystem through batch renaming so that your files and directories can have a consistent naming scheme.
- It offers a comprehensive set of renaming options and scales well from trivial string replacements to more complex operations involving regular expressions.
- F2 prioritises correctness and safety by ensuring that a renaming operation does not result in conflicts or errors. It runs several [validations](https://github.com/ayoisaiah/f2/wiki/Validation-and-conflict-detection) before carrying out a renaming operation and provides an easy way to automatically [fix any detected conflicts](https://github.com/ayoisaiah/f2/wiki/Validation-and-conflict-detection#auto-fixing-conflicts).
- F2 supports all the standard renaming recipes including (but not limited to) string replacement, insertion of text as a prefix, suffix or other position in the file name, stripping a set of characters, changing the case of a set of letters, using auto incrementing numbers, swapping parts of the file name, e.t.c.
- F2 supports all the standard [renaming recipes](https://github.com/ayoisaiah/f2/wiki/Renaming-Recipes) including (but not limited to) string replacement, insertion of text as a prefix, suffix or other position in the file name, stripping a set of characters, changing the case of a set of letters, using auto incrementing numbers, swapping parts of the file name, e.t.c.
- F2 provides several [built-in variables](https://github.com/ayoisaiah/f2/wiki/Built-in-variables) for added flexibility in the renaming process. These variables are based on file attributes such as Exif information for images and ID3 tags for audio files.
- F2 is very fast and won't waste your time. See [benchmarks](#benchmarks).
- F2 allows you to [revert any renaming operation](https://github.com/ayoisaiah/f2/wiki/Undoing-a-renaming-operation) performed with the program. This means you don't have to worry about making a mistake because you can always get back to the previous state without breaking a sweat.
Expand Down Expand Up @@ -113,7 +113,7 @@ AUTHOR:
Ayooluwa Isaiah <ayo@freshman.tech>
VERSION:
v1.5.1
v1.5.2
FLAGS:
--find <pattern>, -f <pattern> Search <pattern>. Treated as a regular expression by default. Use -s or --string-mode to opt out
Expand All @@ -137,374 +137,16 @@ FLAGS:
--version, -v print the version (default: false)
DOCUMENTATION:
https://github.com/ayoisaiah/f2#examples
https://github.com/ayoisaiah/f2/wiki
WEBSITE:
https://github.com/ayoisaiah/f2
```

## Examples

**Notes**:
- F2 does not make any changes to your filesystem by default (performs a dry run).
- To enforce the changes, include the `--exec` or `-x` flag.
- The `-f` or `--find` flag supports regular expressions and string literals. If omitted, it matches the entire filename of each file.
- The `-r` or `--replace` flag supports [variables](#use-a-variable).
- Hidden files and directories are exempted by default but can be included with the `--hidden` or `-H` flag.

### Basic find and replace

Replace all instances of `Screenshot` in the current directory with `Image`:

```bash
$ f2 -f 'Screenshot' -r 'Image'
+--------------------+---------------+--------+
| INPUT | OUTPUT | STATUS |
+--------------------+---------------+--------+
| Screenshot (1).png | Image (1).png | ok |
| Screenshot (2).png | Image (2).png | ok |
| Screenshot (3).png | Image (3).png | ok |
+--------------------+---------------+--------+
```

By default, find expressions are treated as regex. Use `-s` or `--string-mode` to disable regex. This helps when replacing filenames with characters that have a special meaning in regex such as `- . { } ( [ ] )`.

**Regex enabled**:

```bash
$ f2 -f '\(2021\)' -r '[2022]'
+--------------------------------------+--------------------------------------+--------+
| INPUT | OUTPUT | STATUS |
+--------------------------------------+--------------------------------------+--------+
| No Pressure (2021) S01.E01.2160p.mp4 | No Pressure [2022] S01.E01.2160p.mp4 | ok |
| No Pressure (2021) S01.E02.2160p.mp4 | No Pressure [2022] S01.E02.2160p.mp4 | ok |
| No Pressure (2021) S01.E03.2160p.mp4 | No Pressure [2022] S01.E03.2160p.mp4 | ok |
+--------------------------------------+--------------------------------------+--------+
```

**Regex disabled**:

```bash
$ f2 -f '(2021)' -r '[2022]' -s
+--------------------------------------+--------------------------------------+--------+
| INPUT | OUTPUT | STATUS |
+--------------------------------------+--------------------------------------+--------+
| No Pressure (2021) S01.E01.2160p.mp4 | No Pressure [2022] S01.E01.2160p.mp4 | ok |
| No Pressure (2021) S01.E02.2160p.mp4 | No Pressure [2022] S01.E02.2160p.mp4 | ok |
| No Pressure (2021) S01.E03.2160p.mp4 | No Pressure [2022] S01.E03.2160p.mp4 | ok |
+--------------------------------------+--------------------------------------+--------+
```

### Recursive find and replace

Replace all instances of `js` to `ts` in the current directory and all sub directories (no depth limit by default).

```bash
$ f2 -f 'js' -r 'ts' -R
+---------------------+---------------------+--------+
| INPUT | OUTPUT | STATUS |
+---------------------+---------------------+--------+
| index-01.js | index-01.ts | ok |
| index-02.js | index-02.ts | ok |
| one/index-03.js | one/index-03.ts | ok |
| one/index-04.js | one/index-04.ts | ok |
| one/two/index-05.js | one/two/index-05.ts | ok |
| one/two/index-06.js | one/two/index-06.ts | ok |
+---------------------+---------------------+--------+
```

Use the `--max-depth` or `-m` flag to provide a maximum depth limit:

```bash
$ f2 -f 'js' -r 'ts' -R -m 1
+---------------------+---------------------+--------+
| INPUT | OUTPUT | STATUS |
+---------------------+---------------------+--------+
| index-01.js | index-01.ts | ok |
| index-02.js | index-02.ts | ok |
| one/index-03.js | one/index-03.ts | ok |
| one/index-04.js | one/index-04.ts | ok |
+---------------------+---------------------+--------+
```

### Include directories

Directories are exempted from the renaming operation by default. Use the `-d` or
`--include-dir` flag to include them.

*Original tree*:

```plaintext
.
├── pic-1.avif
└── pics
├── pic-02.avif
└── pic-03.avif
```

```bash
$ f2 -f 'pic' -r 'image' -d -x
```

*Renamed tree*:

```plaintext
.
├── image-1.avif
└── images
├── pic-02.avif
└── pic-03.avif
```

You can also rename only directories by using the `-D` or `--only-dir` flag:

*Original tree*:

```plaintext
.
├── pic-1.avif
└── pics
├── pic-02.avif
└── pic-03.avif
```

```bash
$ f2 -f 'pic' -r 'image' -D -x
```

*Renamed tree*:

```plaintext
.
├── pic-1.avif
└── images
├── pic-02.avif
└── pic-03.avif
```

### Ignore extensions

The file extension is matched by default. If this behaviour is not desired, use
the `--ignore-ext` or `-e` flag:

```bash
$ ls
a-jpeg-file.jpeg file.jpeg
```

```bash
$ f2 -f 'jpeg' -r 'jpg' -e
+------------------+-----------------+--------+
| INPUT | OUTPUT | STATUS |
+------------------+-----------------+--------+
| a-jpeg-file.jpeg | a-jpg-file.jpeg | ok |
+------------------+-----------------+--------+
```

### Strip out unwanted text

You can strip out text by leaving out the `-r` flag. It defaults to an empty string:

```bash
$ f2 -f 'pic-'
+-------------+---------+--------+
| INPUT | OUTPUT | STATUS |
+-------------+---------+--------+
| pic-02.avif | 02.avif | ok |
| pic-03.avif | 03.avif | ok |
+-------------+---------+--------+
```

### Rename using an auto incrementing number

You can specify an auto incrementing integer in the replacement string using the
format below:

- `%d`: 1,2,3 e.t.c
- `%02d`: 01, 02, 03, e.t.c.
- `%03d`: 001, 002, 003, e.t.c.

```bash
$ f2 -f '.*\.' -r '%03d.'
+-----------------------------------------+---------+--------+
| INPUT | OUTPUT | STATUS |
+-----------------------------------------+---------+--------+
| Screenshot from 2020-04-19 22-17-02.png | 001.png | ok |
| Screenshot from 2020-04-19 23-17-02.png | 002.png | ok |
| Screenshot from 2020-04-19 24-17-02.png | 003.png | ok |
+-----------------------------------------+---------+--------+
```

You can also specify the number to start from using the `-n` flag:

```bash
$ f2 -f '.*\.' -r '%03d.' -n 20
+-----------------------------------------+---------+--------+
| INPUT | OUTPUT | STATUS |
+-----------------------------------------+---------+--------+
| Screenshot from 2020-04-19 22-17-02.png | 020.png | ok |
| Screenshot from 2020-04-19 23-17-02.png | 021.png | ok |
| Screenshot from 2020-04-19 24-17-02.png | 022.png | ok |
+-----------------------------------------+---------+--------+
```

### Replace spaces with underscores

```bash
$ f2 -f '\s' -r '_'
+--------------------+--------------------+--------+
| INPUT | OUTPUT | STATUS |
+--------------------+--------------------+--------+
| Screenshot (1).png | Screenshot_(1).png | ok |
| Screenshot (2).png | Screenshot_(2).png | ok |
| Screenshot (3).png | Screenshot_(3).png | ok |
+--------------------+--------------------+--------+
```

### Ignore cases

Use the `-i` or `--ignore-case` flag:

```bash
$ f2 -f 'jpeg' -r 'jpg' -i
+--------+--------+--------+
| INPUT | OUTPUT | STATUS |
+--------+--------+--------+
| a.JPEG | a.jpg | ok |
| b.jpeg | b.jpg | ok |
| c.jPEg | c.jpg | ok |
+--------+--------+--------+
```

### Use regex capture variables

Regex capture variables are supported:

```bash
$ f2 -f '.* S(\d+).E(\d+).*.(mp4)' -r 'S$1 E$2.$3'
+--------------------------------------+-------------+--------+
| INPUT | OUTPUT | STATUS |
+--------------------------------------+-------------+--------+
| No Pressure (2021) S01.E01.2160p.mp4 | S01 E01.mp4 | ok |
| No Pressure (2021) S01.E02.2160p.mp4 | S01 E02.mp4 | ok |
| No Pressure (2021) S01.E03.2160p.mp4 | S01 E03.mp4 | ok |
+--------------------------------------+-------------+--------+
```

```bash
$ f2 -f '(\w+) \((\d+)\).(\w+)' -r '$2-$1.$3'
+--------------------+------------------+--------+
| INPUT | OUTPUT | STATUS |
+--------------------+------------------+--------+
| Screenshot (1).png | 1-Screenshot.png | ok |
| Screenshot (2).png | 2-Screenshot.png | ok |
| Screenshot (3).png | 3-Screenshot.png | ok |
+--------------------+------------------+--------+
```

### Directories are auto created if necessary

Assuming the following directory:

```bash
$ ls
x-y-z.pdf
```

```bash
$ f2 -f '-' -r '/' -x
```

*Result*

```bash
.
└── x
└── y
└── z.pdf
```

Also supports the backslash character for separating paths in Windows only.

```bash
$ ls
x-y-z.pdf
```

```bash
$ f2 -f '-' -r '\' -x
```

### Built-in variables

F2 supports several built-in variables that can be used in the replacement
string. You can include any combination of these variables in the replacement
string and they will all be replaced with their corresponding values. Some
variables are specific to certain file types (e.g exif variables for images and
id3 variables for audio files).

#### Supported variables

- `{{f}}`: The original name of the file or directory (excluding the
extension).
- `{{p}}`: The parent directory name.
- `{{ext}}`: The file extension.

**[Date
variables](https://github.com/ayoisaiah/f2/wiki/Built-in-variables#date-variables)**
for accessing attributes such as file creation time, last modification time,
access time, and more. They must be combined with a [date
token](https://github.com/ayoisaiah/f2/wiki/Built-in-variables#date-tokens).

Available date variables include:
- `ctime`: The time at which file metadata was changed.
- `btime`: File birth time (Windows and macOS only).
- `atime`: The last time the file was accessed or read.
- `mtime`: The last time the contents of the file was modified.
- `now`: The current time.

**[Exif
variables](https://github.com/ayoisaiah/f2/wiki/Built-in-variables#exif-variables)**
for accessing attributes of an image file such as the ISO, width, height,
created date, aperture, model, make, dimensions, focal length, exposure time
e.t.c. Each variable can be used like this: `{{exif.<var>}}` or `{{x.<var>}}` as
in `{{exif.iso}}` or `{{x.lens}}`.

Currently supported Exif variables:
- `iso`: The ISO at which the image was captured.
- `w`: The image width.
- `h`: The image height.
- `model`: The camera model (e.g. Canon EOS 5D Mark III).
- `make`: The camera maker (e.g. Canon).
- `lens`: The lens model.
- `et`: The exposure time (e.g. 1/400s).
- `wh`: The image dimensions (e.g 4032x3024).
- `fnum`: The aperture (e.g. f/1.6).
- `fl`: The focal length of the lens (e.g 52mm)
- `dt`: The image creation date. This must be combined with a [date token](https://github.com/ayoisaiah/f2/wiki/Built-in-variables#date-tokens)
(e.g `{{exif.dt.YYYY}}`).

**ID3 variables** for accessing attributes of an audio file such as the album,
artist, title, format, track number, release year e.t.c. Each variable can be
used like this: `{{id3.<var>}}` as in `{{id3.title}}`.

Currently supported ID3 variables:
- `title`: The title of the track.
- `artist`: The track artist.
- `album_artist`: The album artist.
- `album`: The album name.
- `format`: The file format (e.g VORBIS, ID3v2.3).
- `type`: The file type (e.g MP3, OGG, FLAC).
- `year`: The release year.
- `track`: The track number.
- `total_tracks`: The total number of tracks in the album.
- `disc`: The disc number.
- `total_discs`: The total number of discs in the album.

For more information, examples and a full demonstration of the power of
variables, do consult the [relevant wiki
page](https://github.com/ayoisaiah/f2/wiki/Built-in-variables).
## Documentation

Visit the [wiki page](https://github.com/ayoisaiah/f2/wiki) to learn all the
operations that can be achieved with F2.

## Credits

Expand Down
Loading

0 comments on commit b4d27a8

Please sign in to comment.