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. To revert the changes, run: f2 -u.

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 by using the --undo or -u flag. Here's how:

$ f2 -u -x

Everything is now restored to the previous 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:

• The undo operation must be performed in the same directory as the original renaming operation.
• You can only undo an operation once. You cannot undo an "undo operation", but you can always repeat the original renaming command.