Renaming from a CSV file

F2 provides the ability to rename files according to a CSV file, and it provides a great deal of flexibility when working with such files. The CSV file must contain at least one column. If it contains more than one column, then the column separator must be a comma (,).

Basic usage

The first column in the file should be an absolute or relative path to the source file, while the second column (optional) represents the new name. Use the --csv option when working with CSV files. Here's a sample CSV file (input.csv):

proraw.dng,apple-iphone-12raw.dng
bike.jpeg,dawes-bicycle.jpg

You can use it with the --csv flag as follows:

$ f2 --csv 'input.csv'
+------------+------------------------+--------+
|   INPUT    |         OUTPUT         | STATUS |
+------------+------------------------+--------+
| proraw.dng | apple-iphone-12raw.dng | ok     |
| bike.jpeg  | dawes-bicycle.jpg      | ok     |
+------------+------------------------+--------+

In the above example, F2 assumes that the source files are relative to the current working directory. If the source file paths are absolute, it wouldn't matter where you run the F2 from. Here's input.csv with absolute paths in the first column:

/home/ayo/proraw.dng,apple-iphone-12raw.dng
/home/ayo/pics/bike.jpeg,dawes-bicycle.jpg

F2 will be able to find the files regardless of where you run it from. Keep in mind that only the final part of the path (whether file or directory) is considered for renaming. If you want to rename directories as well, add the -d flag (or -D for only directories).

$pwd
/home/ayo/Downloads
$ f2 --csv 'file.csv'
+--------------------------+----------------------------------+--------+
|          INPUT           |              OUTPUT              | STATUS |
+--------------------------+----------------------------------+--------+
| /home/ayo/proraw.dng     | /home/ayo/apple-iphone-12raw.dng | ok     |
| /home/ayo/pics/bike.jpeg | /home/ayo/pics/dawes-bicycle.jpg | ok     |
+--------------------------+----------------------------------+--------+

If you want to change the location of the output, you can use absolute or relative paths in the second column, but there are some rules:

• If the first column is an absolute path, you must use a relative path in the second. The result will be relative to the source path.
• If the first column is a relative path, you may use either absolute or relative paths in the second.
• If a directory in the second column does not exist, it will be automatically created for you (as usual).

/home/ayo/proraw.dng,pics/apple-iphone-12raw.dng
/home/ayo/pics/bike.jpeg,../dawes-bicycle.jpg

+--------------------------+---------------------------------------+--------+
|          INPUT           |                OUTPUT                 | STATUS |
+--------------------------+---------------------------------------+--------+
| /home/ayo/proraw.dng     | /home/ayo/pics/apple-iphone-12raw.dng | ok     |
| /home/ayo/pics/bike.jpeg | /home/ayo/dawes-bicycle.jpg           | ok     |
+--------------------------+---------------------------------------+--------+

You can also use built-in variables, or indexing schemes in the second column:

proraw.dng,%03d_{{xt.ImageWidth}}x{{xt.ImageHeight}}_{{xt.Model}}.dng
bike.jpeg,{{exif.model}}_{{exif.make}}{{ext}}

$ f2 --csv 'input.csv'
+------------+-------------------------------------+--------+
|   INPUT    |               OUTPUT                | STATUS |
+------------+-------------------------------------+--------+
| proraw.dng | 001_4032x3024_iPhone 12 Pro Max.dng | ok     |
| bike.jpeg  | SM-G975F_samsung.jpeg               | ok     |
+------------+-------------------------------------+--------+

Single-column example

If the CSV file contains just one column, or if you don't want to use the contents of any of the other columns in the file in the renaming operation, you can use the -f and -r flags to rename the files as normal. Here's a single column CSV file:

proraw.dng
bike.jpeg

You can rename using a -f and -r combo. If you want to match the entire file name, leave out -f:

$ f2 --csv 'input.csv' -r '%03d{{ext}}'
+------------+----------+--------+
|   INPUT    |  OUTPUT  | STATUS |
+------------+----------+--------+
| proraw.dng | 001.dng  | ok     |
| bike.jpeg  | 002.jpeg | ok     |
+------------+----------+--------+

You can match a specific set of files by including a find pattern:

$ f2 --csv 'input.csv' -f 'bike.jpeg' -r '%03d{{ext}}'
+-----------+----------+--------+
|   INPUT   |  OUTPUT  | STATUS |
+-----------+----------+--------+
| bike.jpeg | 001.jpeg | ok     |
+-----------+----------+--------+

Missing source files

If a source file cannot be found, the row will be skipped. If your CSV file contains a header, it will also be skipped in this manner. The first row in the input.csv file below will be skipped:

/path/to/non-existent/file.png,404.png
/home/ayo/proraw.dng,pics/apple-iphone-12raw.dng
/home/ayo/pics/bike.jpeg,../dawes-bicycle.jpg

If --verbose is used, each skipped row will be printed to the console. This is helpful in case you want to see which files were skipped.

$ f2 --csv 'input.csv' --verbose
Source file '/path/to/non-existent/file.png' was not found, so row '1' was skipped
+--------------------------+---------------------------------------+--------+
|          INPUT           |                OUTPUT                 | STATUS |
+--------------------------+---------------------------------------+--------+
| /home/ayo/proraw.dng     | /home/ayo/pics/apple-iphone-12raw.dng | ok     |
| /home/ayo/pics/bike.jpeg | /home/ayo/dawes-bicycle.jpg           | ok     |
+--------------------------+---------------------------------------+--------+

CSV variables

F2 provides CSV variables for using content in a column in the renaming operation. Here's the syntax of the variable: {{csv.3}} where 3 is the column number. If you use a variable in the replacement string (or in the second column of the CSV file), it will be substituted with the contents of the specified column if it exists, or an empty string if it does not exist.

Here's a sample CSV file containing information about a set of podcast files

Filename,Podcast name,Description,Date,Duration
episode-001.mp3,History on Steroids,The story of WW2,27-Aug-2006,2hrs47mins
S04E23.m4a,Premier League Show,Where will Sancho fit in at United,31-July-2021,30mins

You can rename the source files using the information contained in the other columns as follows:

$ f2 --csv 'input.csv' -r '{{csv.2}} - {{csv.3}} ({{csv.5}})'
+-----------------+-------------------------------------------------------------------+--------+
|      INPUT      |                              OUTPUT                               | STATUS |
+-----------------+-------------------------------------------------------------------+--------+
| episode-001.mp3 | History on Steroids - The story of WW2 (2hrs47mins)               | ok     |
| S04E23.m4a      | Premier League Show - Where will Sancho fit in at United (30mins) | ok     |
+-----------------+-------------------------------------------------------------------+--------+

You can also use the CSV variables in the second column. It may be preferable if you want to use a different pattern for each file:

Filename,Replacement,Podcast name,Description,Date,Duration
episode-001.mp3,{{csv.3}} - {{csv.4}} ({{csv.6}}),History on Steroids,The story of WW2,27-Aug-2006,2hrs47mins
S04E23.m4a,{{csv.4}} ({{csv.5}}),Premier League Show,Where will Sancho fit in at United,31-July-2021,30mins

Which gives:

$ f2 --csv 'input.csv'
+-----------------+-----------------------------------------------------+--------+
|      INPUT      |                       OUTPUT                        | STATUS |
+-----------------+-----------------------------------------------------+--------+
| episode-001.mp3 | History on Steroids - The story of WW2 (2hrs47mins) | ok     |
| S04E23.m4a      | Where will Sancho fit in at United (31-July-2021)   | ok     |
+-----------------+-----------------------------------------------------+--------+