Recovering from failures

F2's validation process should prevent the most common conflicts for any renaming operation. Despite these checks, the renaming operation may still fail for any of the following reasons:

• The source file is being used by another program.
• The source file does not exist due to it being moved or changed in another program.
• Insufficient permissions to rename the file.

If the renaming of a file fails, the operation is not halted. Rather, the program will proceed to the next file in the list. All the failed renaming operations are aggregated and presented at the end of the process along with the reason why they failed.

Here's an example that attempts to rename the following jpeg files in a directory. A few of these files have been made immutable through the chattr +i <filename> command so that the renaming operation fails for those files.

$ tree
.
├── cedric-letsch-_EHPjZ3aBzU-unsplash.jpeg
├── photo-1478811482469-30ec30b9f534.jpeg
├── photo-1479030160180-b1860951d696.jpeg
├── photo-1488928741225-2aaf732c96cc.jpeg
├── photo-1491308780069-cad9c43c6fdd.jpeg
├── photo-1511787532829-ff2eb827cf4c.jpeg
├── photo-1518516278006-4aca92806257.jpeg
├── photo-1526726538690-5cbf956ae2fd.jpeg
├── photo-1533907650686-70576141c030.jpeg
├── photo-1544672531-10bf64a0da46.jpeg
├── photo-1554110397-9bac083977c6.jpeg
├── photo-1555650645-ff8cf7397d9a.jpeg
├── photo-1592312986148-0286379c890d.jpeg
└── sami-takarautio-JiqalEW6Ml0-unsplash.jpeg

Here's the command to rename the files and the output:

$ f2 -f '.*' -r "unsplash-image-%03d" -ex
+-------------------------------------------+-------------------------+-------------------------+
|                   INPUT                   |         OUTPUT          |         STATUS          |
+-------------------------------------------+-------------------------+-------------------------+
| cedric-letsch-_EHPjZ3aBzU-unsplash.jpeg   | unsplash-image-001.jpeg | success                 |
| photo-1478811482469-30ec30b9f534.jpeg     | unsplash-image-002.jpeg | success                 |
| photo-1479030160180-b1860951d696.jpeg     | unsplash-image-003.jpeg | success                 |
| photo-1488928741225-2aaf732c96cc.jpeg     | unsplash-image-004.jpeg | success                 |
| photo-1491308780069-cad9c43c6fdd.jpeg     | unsplash-image-005.jpeg | success                 |
| photo-1511787532829-ff2eb827cf4c.jpeg     | unsplash-image-006.jpeg | success                 |
| photo-1518516278006-4aca92806257.jpeg     | unsplash-image-007.jpeg | success                 |
| photo-1526726538690-5cbf956ae2fd.jpeg     | unsplash-image-008.jpeg | success                 |
| photo-1533907650686-70576141c030.jpeg     | unsplash-image-009.jpeg | success                 |
| photo-1592312986148-0286379c890d.jpeg     | unsplash-image-013.jpeg | success                 |
| photo-1544672531-10bf64a0da46.jpeg        | unsplash-image-010.jpeg | operation not permitted |
| photo-1554110397-9bac083977c6.jpeg        | unsplash-image-011.jpeg | operation not permitted |
| photo-1555650645-ff8cf7397d9a.jpeg        | unsplash-image-012.jpeg | operation not permitted |
| sami-takarautio-JiqalEW6Ml0-unsplash.jpeg | unsplash-image-014.jpeg | operation not permitted |
+-------------------------------------------+-------------------------+-------------------------+
Some files could not be renamed. The successful operations have been written to .f2_2021-04-24T16-00-37PM.json. To revert the changes, pass this file to the --undo flag.

If an error is detected (as above), the entire renaming operation is printed out with the successes above and failures below. The directory now looks like this:

$ tree
.
├── photo-1544672531-10bf64a0da46.jpeg
├── photo-1554110397-9bac083977c6.jpeg
├── photo-1555650645-ff8cf7397d9a.jpeg
├── sami-takarautio-JiqalEW6Ml0-unsplash.jpeg
├── unsplash-image-001.jpeg
├── unsplash-image-002.jpeg
├── unsplash-image-003.jpeg
├── unsplash-image-004.jpeg
├── unsplash-image-005.jpeg
├── unsplash-image-006.jpeg
├── unsplash-image-007.jpeg
├── unsplash-image-008.jpeg
├── unsplash-image-009.jpeg
└── unsplash-image-013.jpeg

Assuming you don't like the fact that some files were renamed while others were not, you can revert the operation using the JSON file (.f2_2021-04-24T16-00-37PM.json) that was outputted in the previous command. Here's how:

$ f2 -u .f2_2021-04-24T16-00-37PM.json -x

And now, things have been restored to the earlier state:

$ tree
.
├── cedric-letsch-_EHPjZ3aBzU-unsplash.jpeg
├── photo-1478811482469-30ec30b9f534.jpeg
├── photo-1479030160180-b1860951d696.jpeg
├── photo-1488928741225-2aaf732c96cc.jpeg
├── photo-1491308780069-cad9c43c6fdd.jpeg
├── photo-1511787532829-ff2eb827cf4c.jpeg
├── photo-1518516278006-4aca92806257.jpeg
├── photo-1526726538690-5cbf956ae2fd.jpeg
├── photo-1533907650686-70576141c030.jpeg
├── photo-1544672531-10bf64a0da46.jpeg
├── photo-1554110397-9bac083977c6.jpeg
├── photo-1555650645-ff8cf7397d9a.jpeg
├── photo-1592312986148-0286379c890d.jpeg
└── sami-takarautio-JiqalEW6Ml0-unsplash.jpeg

Note that once you undo an operation, the corresponding JSON file is deleted automatically from the filesystem since it's now redundant.