# owl(1) *The moon is bright. The owls are ready for the hunt.* Owl is a file renaming tool; it removes character from file names which are not compatible with `FAT` file systems (typically `FAT32` or `exFAT`). ``` owl OPTIONS FILE1 FILE2 ... ``` Rename `FILE`s given at the command line such that all `FAT`-incompatible characters are removed. By default it replaces invalid characters with `_U{Unicode Code Point}_`, but this can be changed, see the `--strategy` flag below. ## OPTIONS: ### -r, \-\-recurse DIRECTORY Recursively search DIRECTORY for files/directories to rename. Search includes DIRECTORY itself. ### -s, \-\-strategy STRATEGY Change what happens to invalid characters. Choices are: - "remove": just remove the characters. If left with an empty string, rename to "\_empty_". - "represent": replace each character with "\_Unum_", where "num" is the Unicode Code Point of the character. ### -e,\-\-valid-set fat|posix|shell Select which characters are considered "invalid" or "bad". Options are: - fat: Characters which are valid in file names on FAT file systems. This is the default. - posix: The POSIX Portable Filename Character Set `A-Za-z0-9.-_` - shell: Characters that *should* not need to be quoted when used in a shell, i.e. all characters apart from control characters, whitespace, and most punctuation. ### -p,\-\-portable An alias for "\-\-valid-set posix". ### -t,\-\-truncate LENGTH Truncate all given file names to at most `LENGTH` bytes. Note that if you have file names with larger Unicode code points (like CJK characters), you may get unexpected results with this option, though it will not cut the file name part way through a character. ### -c,\-\-replace TARGET:REPLACEMENT1,REPLACEMENT2,... Remove every instance of the string `TARGET` in every file name and replace the first instance with `REPLACEMENT1`, the second with `REPLACEMENT2`, and so on. If there are N `REPLACEMENT`'s and more than N instances of `TARGET` in a file name, all instances after the Nth are replaced by the last replacement. Replacements can be empty. See EXAMPLES below for this one. Remember to quote `TARGET:REPLACEMENT1,...` so that your shell doesn't misinterpret the colon. ### -n, \-\-dry-run Causes Owl to just print a representation of what would be done without actually renaming any files. Checks for name collisions with existing files or other renaming operations are still done. ### -v, \-\-version Show version information. ### -h, \-\-help Show a small help message. ## EXAMPLES Suppose we have a file called ``` PodEp 37: Why are there so many spaces in this file name? ``` in the current working directory. We will refer to it as FILE Then: - The command ``` owl --replace ' :,-,_' FILE ``` will rename FILE to `PodEp37:-Why_are_there_so_many_spaces_in_this_file_name_U3F_` - The command ``` owl --truncate 48 --replace ' :,-,_' FILE ``` will rename FILE to `PodEp37:-Why_are_there_so_many_spaces_in_this_fi` - The command ``` owl --portable --strategy remove --truncate 48 FILE ``` will rename FILE to `PodEp37:Whyaretheresomanyspacesinthisfilename` Now suppose we have files "IMPORTANT FILE?" and "Important File". - If you run ``` owl --strategy remove "IMPORTANT FILE?" ``` owl will just return an error, saying that the new name would collide with "important file". - If you run ``` owl --strategy remove --valid-set posix "IMPORTANT FILE?" "Important File" ``` then owl will will rename one file, but refuse to rename the other, as it would conflict with the now-renamed first file. Note you can use the `--dry-run` flag to check for collisions like this before renaming anything. ## EDGE CASES & OTHER TIDBITS ### What order does owl truncate, remove characters, etc.? Owl does things in the following order: 1. Remove invalid UTF-8 2. Replace stuff (see `--replace` flag) 3. Deal with invalid characters (see `--strategy` flag) 4. Truncate file name The order in which you use the flags does not change this. ### What if the new name Owl chooses for a file already exists? Owl checks before each renaming operation to see if the new name already exists, and skips that file if it does. The check is also case-insensitive. See [EXAMPLES](#examples) for more details. ### What doesn't FAT allow? Mainly `*<>\|/:?'` ### What about whitespace? Some of these (like tab, line feed, and carriage return) are not valid under FAT and will be removed. If a sequence of invalid characters surrounded by spaces is in one of the file names, and the `remove` strategy is being used, then you will be left with multiple whitespace characters in a row. For example, ``` "Really questionable ?? filename" ``` will become ``` "Really questionable filename" ``` with a double space before "filename". ### What about invalid UTF-8? This is removed and replaced with "\_INVALID_". This replacement is done before anything else. ### What about UTF-16/Windows? Owl has only been tested so far on Linux with a UTF-8 locale. UTF-16 support on Windows is likely possible, but has not been tested. Please contact me if you would like Windows support (see below). ### What about other restrictions on file names? Windows (and by extension FAT file systems, which come from Microsoft) may have other restrictions on file names, like specific disallowed names like "CON" or names which ends with a ".". Owl does not check for such things; you should look for those using a tool like `find`. For completeness, the disallowed names are ``` CON,AUX,COM1,COM2COM3,COM4,LPT1,LPT2,LPT3,PRN,NUL ``` ### What about symbolic links (a.k.a. symlinks)? Owl will rename the *link*, but not the file that the link points to, even if the link is broken. If you are having issues with broken symbolic links and are on a POSIX/UNIX-like system, you can use ``` find -L DIRECTORY -type l ``` to find all broken links in DIRECTORY. ## AUTHORS & COPYRIGHT Written by user SixteenThousand of github.com (email thomsixteenthousand@gmail.com) and licensed under the GNU General Public License version 3 (GPL v3). See for more information.