Skip to content
Tutorials Center
My learning

Topics

Lesson 68 of 95 ยท Projects

Project: File Organizer

Write a Bash file organizer that sorts files into folders by extension or month, handles name collisions, supports dry-run, keeps an undo log and has its own tests.

Downloads folders, photo dumps and project directories all end the same way: hundreds of files in one place. In this project you write a file organizer: a script that sorts the files of a directory into sub-folders, either by type (images, documents, ...) or by month. Because moving files is a destructive kind of work, the tool gets the safety features a professional script needs: a dry-run that shows the plan, collision handling that never overwrites anything, an undo log that can reverse the whole operation, and tests.

It practises case statements, parameter expansion, arrays, file tests and safe moves. The structure follows Designing Maintainable Scripts.

The plan

TEXT
  Downloads/                      Downloads/
    holiday.JPG                     images/holiday.JPG
    report.pdf          ----->      documents/report.pdf
    song.mp3                        audio/song.mp3
    notes (no extension)            other/notes
                                    .organizer-undo.log   <- what moved where

Rules the tool follows:

  1. Only regular files directly inside the target directory are moved. Sub-directories and hidden files (names starting with a dot) are left alone, which also makes a second run safe.
  2. A file is never overwritten. If the destination name exists, the new file gets -1, -2, ... before its extension.
  3. Every move is written to an undo log (new path, tab, old path).
  4. -n prints the plan and changes nothing.

Step 1: from extension to category

The extension is whatever follows the last dot. ${name##*.} strips everything up to the last dot, and a check that the name contains a dot at all avoids treating Makefile as its own extension. File systems on Linux are case-sensitive, so PHOTO.JPG and photo.jpg are different names, but they are the same kind of file; lower-case the extension with ${ext,,} before the case.

Bash Step 1: map extensions to categories

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Note the multi-extension name backup.tar.gz: only the last part (gz) counts, which is exactly what we want here. Case patterns separated by | are an easy table to extend; adding a category is one new line.

Step 2: never overwrite, find a free name

mv happily replaces an existing file, so the organizer asks for a free name first. The function below also needs to know about files it has planned to create but has not moved yet (in dry-run mode nothing exists on disk), so it consults an associative array planned as well as the file system.

Bash Step 2: collision-safe target names

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Look at the comment in that example: $(unique_target ...) runs the function in a subshell, so its update of planned would be lost. The example uses a redirect to a file, which runs the function in the current shell. In the final tool the function sets a global variable named TARGET instead and the caller reads it, which is the standard way around the subshell problem (see Subshells, Groups and Environment and Performance, Tricks and Pitfalls).

Step 3: organize by date

Instead of file type, many people want folders like 2026-01. The modification time of a file is available as seconds since 1970 from stat -c %Y (GNU stat; BSD and macOS use stat -f %m), and date -u -d @SECONDS +%Y-%m turns it into a folder name. We touch the demo files with fixed dates, so the output never changes.

Bash Step 3: month folders from modification times

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Using UTC avoids a surprise: a file saved at 23:00 on December 31 in one time zone is already in January somewhere else, and you want the same result on every machine.

Step 4: the complete organizer, with undo and tests

Now we combine the pieces. The script has three actions: organize (default), -n for the plan only, and -u to undo the last organize run using the log. The demo that follows exercises all three; then a small test suite checks the important behaviors, including collisions and that undo restores the original layout.

Bash Step 4: organize.sh with dry-run, undo and tests

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

What the run shows, step by step:

  1. Plan: -n lists each move ([plan] ...), and the count of files in the folder is unchanged.
  2. Organize: files move into category folders. The unrelated inbox/images/report.pdf that was already there does not matter, because report.pdf goes to documents/. Hidden files and the sub-directory stay put.
  3. Undo: the log is read backwards (tac), so if a file was moved twice it is restored in the right order. Each file goes back only if the destination is free, then empty folders left behind are removed. The diff proves the tree is identical to the start.
  4. By month: the same files are now sorted into YYYY-MM folders.
  5. Tests: a tiny check helper runs commands and counts failures. The collision test creates a second report.pdf and verifies that it was renamed report-1.pdf instead of overwriting the first.

Details worth studying in the code:

  • mv -n (no clobber) is a second line of defense: even if pick_target had a bug, mv still refuses to overwrite. The || branch reports a failed move and skips the log line, so the undo log only lists moves that happened. (Newer coreutils make a skipped mv -n return non-zero, older ones return 0; the code works with both.)
  • for file in "$dir"/* skips hidden files automatically, because * does not match a leading dot (see Wildcards and Globbing).
  • The undo loop reads two tab-separated columns with IFS=$'\t' read -r new old. File names containing tabs or newlines would break the log format; a production tool could use NUL-separated records. Documenting a limit is better than pretending it does not exist.
  • After restoring, undo calls rmdir only on the folders that held logged files. rmdir refuses to remove a directory that still has content, and your own empty keep-this-folder is never touched. (An early version of this script used find -empty -delete on the whole directory and deleted that folder; the test directory untouched caught it.)

This tool moves files within one directory tree, so every mv is a cheap rename. Moving across file systems copies the data and then deletes the original; if you extend the tool to sort into another disk, add a verification step before deleting.

Ideas for extending it

  • Recursive mode: use find "$dir" -type f -print0 with a while IFS= read -r -d '' loop to handle sub-directories.
  • Duplicate detection: compare sha256sum values and offer to remove true duplicates instead of renaming them -1.
  • A config file with extension-to-category rules, loaded with the key=value parser from Text Processing Recipes.
  • Date from metadata: photos carry the capture date in EXIF data; the exiftool program (not installed here) can read it, which is more accurate than the modification time.
  • Interactive confirmation: a read -p "Move N files? [y/N]" step, with [[ -t 0 ]] so cron runs skip the question (see Reading Input and Interactive Scripts).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does the organizer lower-case the extension with ${ext,,} before the case statement?

    File names are case-sensitive on Linux, so JPG and jpg are different strings. Lower-casing the extension for matching makes both belong to images, while the file name itself stays unchanged.
  2. 2. What is the role of mv -n when the script already looks for a free name?

    -n means no clobber. Even if the free-name logic had a bug, mv would refuse to replace an existing file.
  3. 3. Why does the undo function read the log with tac (last line first)?

    Reversing history means undoing the newest action first. If the same file was moved more than once, going backwards returns it to the true original location.
  4. 4. Why does pick_target set a global variable instead of printing the name and being called as $(pick_target ...)?

    $(...) forks a subshell. Changes made to variables there, including the planned[] array that tracks pending targets, disappear when it ends. A global result variable keeps everything in the current shell.
  5. 5. Why is the date folder computed in UTC (date -u)?

    A file saved at 23:00 on the last day of a month is in the next month in some time zones. Fixing the zone gives the same result everywhere.

Summary

  • Classify files by the part after the last dot, lower-cased, with a case statement that is easy to extend; treat names without a dot as other.
  • Move only regular, non-hidden files in the target directory, which keeps the tool idempotent.
  • Find a free name (name-1.ext, name-2.ext) and use mv -n, so nothing is ever overwritten. Track planned targets so dry-run and real runs behave the same.
  • Write an undo log of new<TAB>old and replay it in reverse with tac.
  • Use stat -c %Y and date -u -d @N for month folders (GNU syntax; BSD differs).
  • Provide -n, validate options and arguments, and test the main behaviors, including collisions and undo, with a tiny check helper.

Next: Project: A Todo Manager in Bash