From 6e522a102352c883ec161a0a644e9a2db2cb5bd9 Mon Sep 17 00:00:00 2001
From: Hzanib <166854817+Hzanib@users.noreply.github.com>
Date: Fri, 19 Sep 2025 13:52:47 -0400
Subject: [PATCH] update documentation for drive_upload

---
 R/drive_upload.R        | 3 ++-
 man-roxygen/overwrite.R | 3 ++-
 man/drive_cp.Rd         | 3 ++-
 man/drive_create.Rd     | 3 ++-
 man/drive_mkdir.Rd      | 3 ++-
 man/drive_mv.Rd         | 3 ++-
 man/drive_rename.Rd     | 3 ++-
 man/drive_upload.Rd     | 6 ++++--
 man/shortcut_create.Rd  | 3 ++-
 9 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/R/drive_upload.R b/R/drive_upload.R
index 389a5dae7..825bce2e6 100644
--- a/R/drive_upload.R
+++ b/R/drive_upload.R
@@ -60,7 +60,7 @@
 #' # Clean up
 #' drive_rm(chicken)
 #'
-#' # `overwrite = FALSE` errors if something already exists at target filepath
+#' # `overwrite = FALSE` errors if something already exists at target filepath.
 #' # THIS WILL ERROR!
 #' drive_create("name-squatter-upload")
 #' drive_example_local("chicken.jpg") |>
@@ -70,6 +70,7 @@
 #'   )
 #'
 #' # `overwrite = TRUE` moves the existing item to trash, then proceeds
+#' #Use `drive_update()` or `drive_put()` if you want to permissions and file is from an already existing file.
 #' chicken <- drive_example_local("chicken.jpg") |>
 #'   drive_upload(
 #'     name = "name-squatter-upload",
diff --git a/man-roxygen/overwrite.R b/man-roxygen/overwrite.R
index 46b712016..c9ed130db 100644
--- a/man-roxygen/overwrite.R
+++ b/man-roxygen/overwrite.R
@@ -9,7 +9,8 @@
 #'     zero or one, move a pre-existing file to the trash, then carry on. Note
 #'     that the new file does not inherit any properties from the old one, such
 #'     as sharing or publishing settings. It will have a new file ID. An error is
-#'     thrown if two or more pre-existing files are found.
+#'     thrown if two or more pre-existing files are found. Use `drive_update()` or
+#'     `drive_put()` if you want to keep permissions and sharing from an already existing file.
 #'   * `FALSE`: Error if there is any pre-existing file at the filepath.
 #'
 #' Note that existence checks, based on filepath, are expensive operations, i.e.
diff --git a/man/drive_cp.Rd b/man/drive_cp.Rd
index d618b4e85..f7443210c 100644
--- a/man/drive_cp.Rd
+++ b/man/drive_cp.Rd
@@ -51,7 +51,8 @@ files with the same filepath.
 zero or one, move a pre-existing file to the trash, then carry on. Note
 that the new file does not inherit any properties from the old one, such
 as sharing or publishing settings. It will have a new file ID. An error is
-thrown if two or more pre-existing files are found.
+thrown if two or more pre-existing files are found. Use \code{drive_update()} or
+\code{drive_put()} if you want to keep permissions and sharing from an already existing file.
 \item \code{FALSE}: Error if there is any pre-existing file at the filepath.
 }
 
diff --git a/man/drive_create.Rd b/man/drive_create.Rd
index ee67eb7ee..a30bd8c7b 100644
--- a/man/drive_create.Rd
+++ b/man/drive_create.Rd
@@ -44,7 +44,8 @@ files with the same filepath.
 zero or one, move a pre-existing file to the trash, then carry on. Note
 that the new file does not inherit any properties from the old one, such
 as sharing or publishing settings. It will have a new file ID. An error is
-thrown if two or more pre-existing files are found.
+thrown if two or more pre-existing files are found. Use \code{drive_update()} or
+\code{drive_put()} if you want to keep permissions and sharing from an already existing file.
 \item \code{FALSE}: Error if there is any pre-existing file at the filepath.
 }
 
diff --git a/man/drive_mkdir.Rd b/man/drive_mkdir.Rd
index 25f183612..9d3693b39 100644
--- a/man/drive_mkdir.Rd
+++ b/man/drive_mkdir.Rd
@@ -32,7 +32,8 @@ files with the same filepath.
 zero or one, move a pre-existing file to the trash, then carry on. Note
 that the new file does not inherit any properties from the old one, such
 as sharing or publishing settings. It will have a new file ID. An error is
-thrown if two or more pre-existing files are found.
+thrown if two or more pre-existing files are found. Use \code{drive_update()} or
+\code{drive_put()} if you want to keep permissions and sharing from an already existing file.
 \item \code{FALSE}: Error if there is any pre-existing file at the filepath.
 }
 
diff --git a/man/drive_mv.Rd b/man/drive_mv.Rd
index d32f9fe5c..90b1754c7 100644
--- a/man/drive_mv.Rd
+++ b/man/drive_mv.Rd
@@ -44,7 +44,8 @@ files with the same filepath.
 zero or one, move a pre-existing file to the trash, then carry on. Note
 that the new file does not inherit any properties from the old one, such
 as sharing or publishing settings. It will have a new file ID. An error is
-thrown if two or more pre-existing files are found.
+thrown if two or more pre-existing files are found. Use \code{drive_update()} or
+\code{drive_put()} if you want to keep permissions and sharing from an already existing file.
 \item \code{FALSE}: Error if there is any pre-existing file at the filepath.
 }
 
diff --git a/man/drive_rename.Rd b/man/drive_rename.Rd
index 83952916b..c467bee2e 100644
--- a/man/drive_rename.Rd
+++ b/man/drive_rename.Rd
@@ -24,7 +24,8 @@ files with the same filepath.
 zero or one, move a pre-existing file to the trash, then carry on. Note
 that the new file does not inherit any properties from the old one, such
 as sharing or publishing settings. It will have a new file ID. An error is
-thrown if two or more pre-existing files are found.
+thrown if two or more pre-existing files are found. Use \code{drive_update()} or
+\code{drive_put()} if you want to keep permissions and sharing from an already existing file.
 \item \code{FALSE}: Error if there is any pre-existing file at the filepath.
 }
 
diff --git a/man/drive_upload.Rd b/man/drive_upload.Rd
index 9bf5ae0bb..64c729d3b 100644
--- a/man/drive_upload.Rd
+++ b/man/drive_upload.Rd
@@ -57,7 +57,8 @@ files with the same filepath.
 zero or one, move a pre-existing file to the trash, then carry on. Note
 that the new file does not inherit any properties from the old one, such
 as sharing or publishing settings. It will have a new file ID. An error is
-thrown if two or more pre-existing files are found.
+thrown if two or more pre-existing files are found. Use \code{drive_update()} or
+\code{drive_put()} if you want to keep permissions and sharing from an already existing file.
 \item \code{FALSE}: Error if there is any pre-existing file at the filepath.
 }
 
@@ -108,7 +109,7 @@ purrr::pluck(chicken, "drive_resource", 1, "starred")
 # Clean up
 drive_rm(chicken)
 
-# `overwrite = FALSE` errors if something already exists at target filepath
+# `overwrite = FALSE` errors if something already exists at target filepath.
 # THIS WILL ERROR!
 drive_create("name-squatter-upload")
 drive_example_local("chicken.jpg") |>
@@ -118,6 +119,7 @@ drive_example_local("chicken.jpg") |>
   )
 
 # `overwrite = TRUE` moves the existing item to trash, then proceeds
+#Use `drive_update()` or `drive_put()` if you want to permissions and file is from an already existing file.
 chicken <- drive_example_local("chicken.jpg") |>
   drive_upload(
     name = "name-squatter-upload",
diff --git a/man/shortcut_create.Rd b/man/shortcut_create.Rd
index a25401794..b301f13af 100644
--- a/man/shortcut_create.Rd
+++ b/man/shortcut_create.Rd
@@ -35,7 +35,8 @@ files with the same filepath.
 zero or one, move a pre-existing file to the trash, then carry on. Note
 that the new file does not inherit any properties from the old one, such
 as sharing or publishing settings. It will have a new file ID. An error is
-thrown if two or more pre-existing files are found.
+thrown if two or more pre-existing files are found. Use \code{drive_update()} or
+\code{drive_put()} if you want to keep permissions and sharing from an already existing file.
 \item \code{FALSE}: Error if there is any pre-existing file at the filepath.
 }