Recovering from failures

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

• The source file is being used by another program.
• The source file no longer exists due to it being moved or changed in another program.
• Insufficient permissions to rename the file.

When the renaming of a file fails, the entire 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 on Linux 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 -r "unsplash-image-%03d" -e -x
+-------------------------------------------+-------------------------+-------------------------+
|                   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 command must be executed 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.

Learn more about how undo works.