push behavior with version-aware remotes (#4945)

* push behavior with version-aware remotes * ref: update desc of push
iterative · Oct 21, 2023 · 9a38c9e · 9a38c9e
1 parent b821832
commit 9a38c9e
Show file tree

Hide file tree

Showing 3 changed files with 44 additions and 1 deletion.
diff --git a/content/docs/command-reference/install.md b/content/docs/command-reference/install.md
@@ -3,6 +3,15 @@
 Install Git hooks into the <abbr>DVC repository</abbr> to automate certain
 common actions.
 
+<admon type="warn">
+
+Do not use these Git hooks if you are using a
+[version-aware remote](/doc/user-guide/data-management/cloud-versioning#version-aware-remotes).
+Version-aware remotes require running `dvc push` before `git commit`, which is
+not supported by the included hooks.
+
+</admon>
+
 ## Synopsis
 
 ```usage

diff --git a/content/docs/command-reference/push.md b/content/docs/command-reference/push.md
@@ -1,7 +1,8 @@
 # push
 
 Upload tracked files or directories to [remote storage] based on the current
-`dvc.yaml` and `.dvc` files.
+<abbr>dvc files</abbr> files (and update the cloud info in those files if
+pushing to a [version-aware] remote).
 
 [remote storage]: /doc/user-guide/data-management/remote-storage
 
@@ -332,3 +333,32 @@ $ aws s3api list-object-versions --bucket mybucket
         }
     ]
 ```
+
+With `version_aware` enabled, `dvc push` will also modify <abbr>dvc files</abbr>
+to capture the version information:
+
+```cli
+...
+    outs:
+    - path: data/prepared
+      hash: md5
+      files:
+      - relpath: test.tsv
+        md5: b656f1a8273d0c541340cb129fd5d5a9
+        size: 1708591
+        cloud:
+          versioned_store:
+            etag: b656f1a8273d0c541340cb129fd5d5a9
+            version_id: T6rFr7NSHkL3v9tGStO7GTwsVaIFl42T
+      - relpath: train.tsv
+        md5: 9ca281786366acca17632c27c5c5cc75
+        size: 6728772
+        cloud:
+          versioned_store:
+            etag: 9ca281786366acca17632c27c5c5cc75
+            version_id: XaYsHQHWK219n5MoCRe.Rr7LeNbbder_
+...
+```
+
+Always `dvc push` before `git commit` so that the updated cloud version info is
+available in Git.
diff --git a/content/docs/user-guide/data-management/cloud-versioning.md b/content/docs/user-guide/data-management/cloud-versioning.md
@@ -82,6 +82,10 @@ When the `version_aware` option is enabled on a `dvc remote`:
 - `dvc fetch` and `dvc pull` will download the corresponding version of an
   object from cloud storage.
 
+With `version_aware` enabled, `dvc push` will modify <abbr>dvc files</abbr>.
+Always `dvc push` before `git commit` so that the updated cloud version info is
+available in Git.
+
 <admon type="warn">
 
 Note that when `version_aware` is in use, DVC does not delete current versions