F2 - Command-line batch renaming tool
F2 is a cross-platform command-line tool for batch renaming files and directories quickly and safely. Written in Go!
⚡ Installation
F2 is written in Go, so you can install it through go install (requires Go
1.19 or later):
go install github.com/ayoisaiah/f2/cmd/f2@latest📦 NPM package
You can also install F2 via its npm package:
With npm:
npm i @ayoisaiah/f2 -gWith yarn:
yarn global add @ayoisaiah/f2Other installation methods are available here.
💥 Why should you use F2?
- 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 before carrying out a renaming operation, and provides an easy way to automatically fix any detected 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 provides several 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 also supports utilising tags from the popular exiftool which should cover most use cases.
- F2 is very fast and won't waste your time. See benchmarks.
- F2 allows you to revert any 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.
- F2 has good test coverage with equal attention paid to all supported platforms (Linux, Windows and macOS).
- F2 is well documented so that you won't have to scratch your head while figuring out what you can do with it. Lots of realistic examples are provided to aid comprehension.
✨ Main features
- Safe and transparent. F2 uses a dry run mode by default so you can review the exact changes that will be made to your filesystem before making them.
- Cross-platform with full support for Linux, macOS, and Windows. It also runs on less commonly-used platforms, like Termux (Android).
- Extremely fast, even when working with a large amount of files.
- Supports the chaining of several consecutive renaming operations before a final output is produced.
- Automatically detects potential conflicts such as file collisions, or overrides and reports them to you.
- Provides several built-in variables for the easier renaming of certain file types.
- Provides easy access to all ~25,000 tags in exiftool for maximum flexibility in renaming.
- Supports find and replace using regular expressions, including capture groups.
- Ignores hidden directories and files by default.
- Respects the
NO_COLORenvironmental variable. - Supports limiting the number of replaced matches, and you can start from the beginning or end of the file name.
- Supports recursive renaming for both files and directories.
- Supports renaming only files, or only directories, or both.
- Supports using an ascending integer for renaming (e.g 001, 002, 003, e.t.c.), and it can be formatted in several ways.
- Supports undoing the last renaming operation in case of mistakes or errors.
- Supports renaming from a CSV file.
- Extensive documentation and examples for each option that is provided.
💻 Screenshots
📃 Documentation
Visit the wiki page to view usage examples and learn about all the renaming operations that can be achieved with F2.
🔥 Benchmarks
Environment
- OS: Ubuntu 20.04.2 LTS on Windows 10 x86_64
- CPU: Intel i7-7560U (4) @ 2.400GHz
- Kernel: 4.19.128-microsoft-standard
Renaming 10,000 MP3 files using their ID3 attributes (~1.6 seconds):
hyperfine --warmup 3 'f2 -f ".*" -r "{{id3.artist}}_{{id3.album}}_{{id3.track}}_{{r} }.mp3" -x'
Benchmark #1: f2 -f ".*" -r "{{id3.artist}}_{{id3.album}}_{{id3.track}}_{{r}}.mp3" -x
Time (mean ± σ): 1.691 s ± 0.031 s [User: 1.326 s, System: 0.744 s]
Range (min … max): 1.634 s … 1.736 s 10 runsRenaming 100,000 files using a random string and an auto incrementing integer (~5 seconds):
hyperfine --warmup 3 'f2 -f ".*" -r "{{r}}_%03d" -x'
Benchmark #1: f2 -f ".*" -r "{{r}}_%03d" -x
Time (mean ± σ): 4.938 s ± 0.328 s [User: 2.792 s, System: 2.770 s]
Range (min … max): 4.421 s … 5.474 s 10 runsRenaming 100,000 JPEG files using their Exif attributes (~30 seconds):
hyperfine --warmup 3 'f2 -f ".*" -r "{{x.make}}_{{x.model}}_{{x.iso}}_{{x.wh}}_{{r}}_%03d.jpg" -x'
Benchmark #1: f2 -f ".*" -r "{{x.make}}_{{x.model}}_{{x.iso}}_{{x.wh}}_{{r}}_%03d.jpg" -x
Time (mean ± σ): 31.143 s ± 1.691 s [User: 34.792 s, System: 4.779 s]
Range (min … max): 29.317 s … 33.355 s 10 runsWindows
Renaming 10,000 MP3 files with an auto incrementing integer through native PowerShell commands (~30 seconds):
Measure-Command { Get-ChildItem *.mp3 | ForEach-Object -Begin { $count = 1 } -Process { Rename-Item $_ -NewName "music_$count.mp3"; $count++ } }
Days : 0
Hours : 0
Minutes : 0
Seconds : 29
Milliseconds : 582
Ticks : 295824810
TotalDays : 0.000342389826388889
TotalHours : 0.00821735583333333
TotalMinutes : 0.49304135
TotalSeconds : 29.582481
TotalMilliseconds : 29582.481Renaming 10,000 MP3 files with an auto incrementing integer through F2 (~12 seconds):
Measure-Command { f2 -f ".*" -r "audio_%03d.mp3" -x }
Days : 0
Hours : 0
Minutes : 0
Seconds : 11
Milliseconds : 634
Ticks : 116342215
TotalDays : 0.000134655341435185
TotalHours : 0.00323172819444444
TotalMinutes : 0.193903691666667
TotalSeconds : 11.6342215
TotalMilliseconds : 11634.2215🤝 Contribute
Bug reports and feature requests are much welcome! Please open an issue before creating a pull request.
⚖ Licence
Created by Ayooluwa Isaiah and released under the terms of the MIT Licence.