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 a n ownCloud rule but an OS dependency. |
Here are some rules of thumb
|
Examples and Pitfalls
The following examples are put on top of this document to highlight file naming issues that can be avoided easily.
-
If you create a file in Linux or macOS like
my-filename.
(see the dot at the end) ormy-filename.LPT1
(see the reserved name LPT1), you can sync the file with your Desktop App if the mount target is on Linux. If a Windows user tries to synchronize these files, Windows will reject 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. -
If you rename an existing file in Linux or macOS by just changing the case like
ownCloud
→ownCloud
, it is very likely to get problems on the Windows side because the file looks (and is) the same for Windows.
Maximum Path Length Limitation
Although every file system has its limits, as described in Wikipedia: Comparison of file systems, you will normally rarely reach them. However, this can change when using application programming interfaces (APIs) to create files, especially on Windows and especially when using the Virtual Files (VFS) feature. Here, with the Windows default setting, the _path component for an API-created file is limited to 260 characters - which can be reached quickly.
When using the Desktop for Windows with VFS configured, files may not be synchronized if the source file was created in an environment where the path component exceeds the 260-character limit.
In such a case, the Desktop App will notify the user about the inability to sync the particular file.
Path Length fix for Windows
To get around the 260 character maximum path length limitation, Microsoft has provided a solution document where they describe the opt-in process to relax the path length limitation when using API calls, as 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 or macOS file systems to create files with control characters in the filename, they may 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 Important Rules
- Windows
-
Filenames must not end with a space or a dot.
- Linux or macOS
-
When the Desktop App is on Linux or macOS and the server you sync to is on Windows, you cannot have the same file or folder name but with different casings. A cross icon will appear, indicating that indicates that the file can’t be synced. Files on Linux or macOS must match with the Windows rules for a successful sync.