Filename Considerations

Introduction

When using the Desktop App, depending on the operating system (OS) you are using, file and folder names and their lengths can have different restrictions. Creating files and folders with allowed names or maximum lengths on one OS, may have issues or even can´t be synced because of different rules in another OS. This page gives you a brief overview of limitations regarding file and folder names on different operating systems.

This is not an ownCloud rule but an OS dependency
Here are some rules of thumb

  1. Do not use any of the mentioned characters or words in any OS when using the Desktop App.

  2. When the Desktop App is on Linux/Unix and the target mount to sync on is on SMB, file and folder names on Linux/Unix must comply with the Windows rules for successful syncing.

  3. When the Desktop App is on Linux/Unix and the target mount to sync on is on SMB and you want to just rename the file with different casings, rename the file to a total different name, let it sync and then rename it again to the name that you want.

  4. When the source file is on an environment that allows the path component of the path/filename length exceeding 260 characters, the file will not be syncable to a Windows standard client without additional measures. For details see below.

Maximum Path Length Limitation

Though each file system has its limits as described in Wikipedia: Comparison of file systems, you normally will rarely reach them. On the other hand, when using programming interfaces (APIs) to create files, this can change, especially on Windows and in particular when using the Virtual Files (VFS) feature. Here, with the default Windows setting, the path component for a file created via API is limited to 260 characters - which can be reached quickly.

When using the Desktop App for Windows with VFS configured, files may not be able to be synced if the source file was created in an environment where the path component exceeded the 260 character limit.

In such a case, the Desktop App notifies the user about the inability of syncing the particular file.

Fix for Windows

To overcome the maximum path length limitation of 260 characters, Microsoft has provided a solution document where they describe the opt-in process to relax the path length limitation when using API calls, like VFS does when creating files and folders.

Forbidden Printable ASCII Characters

Linux/Unix

/ (forward slash)

Windows

< (less than)
> (greater than)
: (colon - sometimes works, but is actually NTFS Alternate Data Streams)
" (double quote)
/ (forward slash)
\ (backslash)
| (vertical bar or pipe)
? (question mark)
* (asterisk)

Non-Printable Characters

If your files are created via a program, do not use non-printable characters. See the Wikipedia "Control code chart" section for more information on ASCII control characters.

Linux/Unix

0 (NULL byte)

While it is legal under Linux/Unix file systems to create files with control characters in the filename, they might be inaccessible and/or unsyncable.
Windows

0-31 (ASCII control characters)

Reserved File Names

The following file names are reserved:

Windows

CON, PRN, AUX, NUL COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9

Other Rules

Linux/Unix

When the Desktop App is on Linux/Unix and the target mount to sync on is on SMB, you cannot have the same file or folder name but with different casings. A cross icon will be shown that indicates that the file can’t be synced. Files on Linux/Unix must comply with the Windows rules for successful syncing.

Windows

Filenames cannot end in a space or dot

Examples and Pitfalls

  1. When creating a file in Linux/Unix like my-filename. (see the dot at the end) or my-filename.LPT1 (see the reserved name LPT1), you can sync the file to your ownCloud if the mount target is Linux/Unix. When a Windows user tries to sync these files, Windows rejects the file. Comparing the file list in both environments shows that one side has more files than the other. There will be no notification as this is an OS dependency.

  2. When renaming an existing file in Linux/Unix by just changing the casing like owncloud → ownCloud, you might get issues on the windows sync side as for Windows the file looks the same.