From 27a3c72e7196f0317807c35d464013caad047d93 Mon Sep 17 00:00:00 2001 From: Anja Barz Date: Thu, 7 Aug 2025 14:25:23 +0200 Subject: [PATCH 1/4] add file name rules for desktop --- docs/user/desktop-client/file-names.md | 62 ++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 docs/user/desktop-client/file-names.md diff --git a/docs/user/desktop-client/file-names.md b/docs/user/desktop-client/file-names.md new file mode 100644 index 00000000..8576c160 --- /dev/null +++ b/docs/user/desktop-client/file-names.md @@ -0,0 +1,62 @@ +--- +sidebar_position: 11 +id: file-names +title: File Naming Rules +description: File Naming Rules for OpenCloud Desktop +draft: true +--- + +# Filename restrictions on OpenCloud Desktop + +When using the OpenCloud Desktop Client, file and folder names must meet certain operating system (OS) requirements to ensure seamless sync across different platforms. These restrictions are not enforced by OpenCloud but originate from system limitations. + +## Key Guidelines + +1. Avoid using prohibited characters or reserved words in filenames on any OS. +2. If syncing from Linux/macOS to a Windows-based share, ensure filenames follow Windows naming rules. +3. To change casing (e.g., `File.txt` → `file.txt`) on Linux/macOS when syncing to Windows, rename the file to a completely new name, let it sync, then rename it to the desired casing. + +## Common Limitations + +### a. Maximum Path Length + +- Some environments allow long filenames but Windows has a default limit of 260 characters when using APIs (e.g., VFS). Exceeding this limit may result in sync errors, often with notifications in-app +- Windows 10 and later versions can lift this limit if explicitly enabled (see Microsoft’s documentation). + +### b. Forbidden Characters + +| OS | Forbidden Characters | +| --------------- | ------------------------------- | ------------ | +| **Linux/macOS** | `/` | +| **Windows** | `<`, `>`, `:`, `"`, `/`, `\`, ` | `, `?`, `\*` | + +### c. Non-Printable ASCII Characters + +- Linux/macOS: NUL (character code 0) +- Windows: ASCII 0 – 31 + While valid on some systems, such characters often cause issues during syncing. + +### d. Reserved Filenames (Windows) + +Avoid using any of the following as filenames: +`CON`, `PRN`, `AUX`, `NUL`, `COM1`–`COM9`, `LPT1`–`LPT9` + +### e. Special Rules + +- On Linux/macOS syncing to SMB, filenames that differ only by case may cause conflicts—rename files clearly to avoid sync failures. +- Windows: Filenames must not end in a space or period (`.`). + +## Example + +Creating a file named `example.` or `example.LPT1` on macOS may sync to OpenCloud successfully. However, when accessed via a Windows client, these files may be rejected due to reserved naming or format rules, leading to inconsistent sync behavior across devices. + +## Summary + +| Restriction Type | Action Item | +| -------------------- | ------------------------------------------------ | +| Path Length | Keep paths under ~260 characters unless extended | +| Forbidden Characters | Remove disallowed characters from names | +| Control Characters | Avoid non-printable ASCII characters | +| Reserved Filenames | Do not use Windows reserved names | +| Case-Only Changes | Rename to a temporary name before syncing | +| Trailing Characters | Avoid filenames ending in space or period | From 1c6cda170b54223111bbc8dadad5ff39a3830793 Mon Sep 17 00:00:00 2001 From: Anja Barz Date: Mon, 11 Aug 2025 12:47:26 +0200 Subject: [PATCH 2/4] make proposed changes --- docs/user/desktop-client/file-names.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/user/desktop-client/file-names.md b/docs/user/desktop-client/file-names.md index 8576c160..6533104e 100644 --- a/docs/user/desktop-client/file-names.md +++ b/docs/user/desktop-client/file-names.md @@ -12,22 +12,24 @@ When using the OpenCloud Desktop Client, file and folder names must meet certain ## Key Guidelines -1. Avoid using prohibited characters or reserved words in filenames on any OS. -2. If syncing from Linux/macOS to a Windows-based share, ensure filenames follow Windows naming rules. -3. To change casing (e.g., `File.txt` → `file.txt`) on Linux/macOS when syncing to Windows, rename the file to a completely new name, let it sync, then rename it to the desired casing. +- Avoid using prohibited characters or reserved words in filenames on any OS. +- If syncing from Linux/macOS to a Windows-based share, make sure filenames are compatible with Windows naming restrictions. +- To change casing (e.g., `File.txt` → `file.txt`) on Linux/macOS when syncing to Windows, rename the file to a completely new name, let it sync, then rename it to the desired casing. ## Common Limitations ### a. Maximum Path Length -- Some environments allow long filenames but Windows has a default limit of 260 characters when using APIs (e.g., VFS). Exceeding this limit may result in sync errors, often with notifications in-app -- Windows 10 and later versions can lift this limit if explicitly enabled (see Microsoft’s documentation). +Windows limits file paths to 260 characters by default. +If your sync root exceeds this, the Desktop Client will warn: +"The path '%1' is too long. Please enable long paths in the Windows settings or choose a different folder." + +On Windows 10 and later, you can remove this limit by enabling Long Paths. See [Microsoft’s documentation](https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=registry#enable-long-paths-in-windows-10-version-1607-and-later). ### b. Forbidden Characters | OS | Forbidden Characters | | --------------- | ------------------------------- | ------------ | -| **Linux/macOS** | `/` | | **Windows** | `<`, `>`, `:`, `"`, `/`, `\`, ` | `, `?`, `\*` | ### c. Non-Printable ASCII Characters From 434a4f7f151bad46d763380d27e7842a434d47e9 Mon Sep 17 00:00:00 2001 From: Anja Barz Date: Mon, 11 Aug 2025 14:25:54 +0200 Subject: [PATCH 3/4] change the placeholder --- docs/user/desktop-client/file-names.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user/desktop-client/file-names.md b/docs/user/desktop-client/file-names.md index 6533104e..a784b3ae 100644 --- a/docs/user/desktop-client/file-names.md +++ b/docs/user/desktop-client/file-names.md @@ -22,7 +22,7 @@ When using the OpenCloud Desktop Client, file and folder names must meet certain Windows limits file paths to 260 characters by default. If your sync root exceeds this, the Desktop Client will warn: -"The path '%1' is too long. Please enable long paths in the Windows settings or choose a different folder." +"The path 'YOUR.LONG.PATH' is too long. Please enable long paths in the Windows settings or choose a different folder." On Windows 10 and later, you can remove this limit by enabling Long Paths. See [Microsoft’s documentation](https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=registry#enable-long-paths-in-windows-10-version-1607-and-later). @@ -30,7 +30,7 @@ On Windows 10 and later, you can remove this limit by enabling Long Paths. See [ | OS | Forbidden Characters | | --------------- | ------------------------------- | ------------ | -| **Windows** | `<`, `>`, `:`, `"`, `/`, `\`, ` | `, `?`, `\*` | +| Windows | `<`, `>`, `:`, `"`, `/`, `\`, ` | `, `?`, `\*` | ### c. Non-Printable ASCII Characters From 6ccc768b3db9404c332b37e77e2f23a2422a09ca Mon Sep 17 00:00:00 2001 From: Anja Barz Date: Mon, 11 Aug 2025 14:30:42 +0200 Subject: [PATCH 4/4] fix issues --- docs/user/desktop-client/file-names.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user/desktop-client/file-names.md b/docs/user/desktop-client/file-names.md index a784b3ae..2bea92e7 100644 --- a/docs/user/desktop-client/file-names.md +++ b/docs/user/desktop-client/file-names.md @@ -28,9 +28,9 @@ On Windows 10 and later, you can remove this limit by enabling Long Paths. See [ ### b. Forbidden Characters -| OS | Forbidden Characters | -| --------------- | ------------------------------- | ------------ | -| Windows | `<`, `>`, `:`, `"`, `/`, `\`, ` | `, `?`, `\*` | +| OS | Forbidden Characters | +| ------- | ------------------------------- | ------------ | +| Windows | `<`, `>`, `:`, `"`, `/`, `\`, ` | `, `?`, `\*` | ### c. Non-Printable ASCII Characters