From 683cf536e05737dbaa634d7e983934085dceefaf Mon Sep 17 00:00:00 2001
From: ZeroAdark <159731431+ZeroAdark@users.noreply.github.com>
Date: Sat, 1 Aug 2026 00:15:22 -0400
Subject: [PATCH] docs: clarify S3 builder URL path behavior

---
 src/aws/builder.rs | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/aws/builder.rs b/src/aws/builder.rs
index b09c6659..7d2a37c9 100644
--- a/src/aws/builder.rs
+++ b/src/aws/builder.rs
@@ -631,12 +631,15 @@ impl AmazonS3Builder {
     ///
     /// Note: Settings derived from the URL will override any others set on this builder
     ///
+    /// A path in the URL is not retained as a prefix. Use [`crate::parse_url`] to create
+    /// an object store and return the path separately.
+    ///
     /// # Example
     /// ```
     /// use object_store::aws::AmazonS3Builder;
     ///
     /// let s3 = AmazonS3Builder::from_env()
-    ///     .with_url("s3://bucket/path")
+    ///     .with_url("s3://bucket")
     ///     .build();
     /// ```
     pub fn with_url(mut self, url: impl Into<String>) -> Self {