From f7b255d4ec760e4d1fe28fe2f064bb02261207b4 Mon Sep 17 00:00:00 2001
From: Johannes Rothe <mail@johannes-rothe.de>
Date: Thu, 27 Nov 2025 22:07:26 +0100
Subject: [PATCH] googlecloudstorage: improve endpoint parameter docs

When specifying a custom endpoint with a subpath, there is a limitation
in the Google cloud storage integration that the subpath is ignored
during upload operations. For example with the custom endpoint
"example.org/custom/endpoint" on upload the /custom/endpoint is not
reflected.

As this is most likely an issue with the underlying API client, there is
no way to fix this in rclone. By extending the documentation at least
rclone users are made aware of this limitation.

Related forum thread: https://forum.rclone.org/t/googlecloudstorage-custom-endpoint-subpath-removed-for-upload/53059
---
 .../googlecloudstorage/googlecloudstorage.go  | 21 +++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/backend/googlecloudstorage/googlecloudstorage.go b/backend/googlecloudstorage/googlecloudstorage.go
index 449e371bc..3c9062be7 100644
--- a/backend/googlecloudstorage/googlecloudstorage.go
+++ b/backend/googlecloudstorage/googlecloudstorage.go
@@ -346,9 +346,26 @@ can't check the size and hash but the file contents will be decompressed.
 			Advanced: true,
 			Default:  false,
 		}, {
-			Name:     "endpoint",
-			Help:     "Endpoint for the service.\n\nLeave blank normally.",
+			Name: "endpoint",
+			Help: `Custom endpoint for the storage API. Leave blank to use the provider default.
+
+When using a custom endpoint that includes a subpath (e.g. example.org/custom/endpoint),
+the subpath will be ignored during upload operations due to a limitation in the
+underlying Google API Go client library.
+Download and listing operations will work correctly with the full endpoint path.
+If you require subpath support for uploads, avoid using subpaths in your custom
+endpoint configuration.`,
 			Advanced: true,
+			Examples: []fs.OptionExample{{
+				Value: "storage.example.org",
+				Help:  "Specify a custom endpoint",
+			}, {
+				Value: "storage.example.org:4443",
+				Help:  "Specifying a custom endpoint with port",
+			}, {
+				Value: "storage.example.org:4443/gcs/api",
+				Help:  "Specifying a subpath, see the note, uploads won't use the custom path!",
+			}},
 		}, {
 			Name:     config.ConfigEncoding,
 			Help:     config.ConfigEncodingHelp,