diff --git a/content/docs/command-reference/install.md b/content/docs/command-reference/install.md
index ea1a9e3325..50416432d5 100644
--- a/content/docs/command-reference/install.md
+++ b/content/docs/command-reference/install.md
@@ -3,6 +3,15 @@
Install Git hooks into the DVC repository to automate certain
common actions.
+
+
+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.
+
+
+
## Synopsis
```usage
diff --git a/content/docs/command-reference/push.md b/content/docs/command-reference/push.md
index acfef0eea4..914f1ab6a8 100644
--- 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.
+dvc files 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 dvc files
+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
index fcb04bb00b..2413122a89 100644
--- 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 dvc files.
+Always `dvc push` before `git commit` so that the updated cloud version info is
+available in Git.
+
Note that when `version_aware` is in use, DVC does not delete current versions