guide: remote storage

content/docs/command-reference/config.md

@@ -122,7 +122,7 @@ within:
 
 ### core
 
-- `core.remote` - name of the remote storage to use by default.
+- `core.remote` - name of the [remote storage](#remote) to use by default.
 
 - `core.interactive` - whether to always ask for confirmation before reproducing
   each [stage](/doc/command-reference/run) in `dvc repro`. (Normally, this
@@ -157,9 +157,30 @@ within:
 
 ### remote
 
-All `remote` sections contain a `url` value and can also specify `user`, `port`,
-`keyfile`, `timeout`, `ask_password`, and other cloud-specific key/value pairs.
-See `dvc remote add` and `dvc remote modify` for more information.
+Unlike most other sections, configuration files may have more than one
+`'remote'`. All of them require a unique `"name"` and a `url` value. They can
+also specify `jobs`, `verify`, and many platform-specific key/value pairs like
+`port` and `password`.
+
+<admon icon="book">
+
+See [Remote Storage Configuration] for more details.
+
+[remote storage configuration]:
+  /doc/user-guide/data-management/remote-storage#configuration
+
+</admon>
+
+For example, the following config file defines a `temp` remote in the local file
+system (located in `/tmp/dvcstore`), and marked as default (via [`core`](#core)
+section):
+
+```ini
+['remote "temp"']
+    url = /tmp/dvcstore
+[core]
+    remote = temp
+```
 
 ### cache
 

content/docs/command-reference/remote/add.md

@@ -1,9 +1,13 @@
 # remote add
 
-Add a new [data remote](/doc/command-reference/remote).
+Register a new [DVC remote](/doc/user-guide/data-management/remote-storage).
 
-> Depending on your storage type, you may also need `dvc remote modify` to
-> provide credentials and/or configure other remote parameters.
+<admon type="tip">
+
+Depending on your storage type, you may also need `dvc remote modify` to provide
+credentials and/or configure other remote parameters.
+
+</admon>
 
 ## Synopsis
 
@@ -26,9 +30,9 @@ for the first remote):
 
 ```ini
 ['remote "myremote"']
-url = /tmp/dvcstore
+    url = /tmp/dvcstore
 [core]
-remote = myremote
+    remote = myremote
 ```
 
 > 💡 Default remotes are expected by commands that accept a `-r`/`--remote`
@@ -379,10 +383,10 @@ Using an absolute path (recommended):
 ```cli
 $ dvc remote add -d myremote /tmp/dvcstore
 $ cat .dvc/config
-  ...
-  ['remote "myremote"']
-        url = /tmp/dvcstore
-  ...
+...
+['remote "myremote"']
+    url = /tmp/dvcstore
+...
 ```
 
 > Note that the absolute path `/tmp/dvcstore` is saved as is.
@@ -393,10 +397,10 @@ directory, but saved **relative to the config file location**:
 ```cli
 $ dvc remote add -d myremote ../dvcstore
 $ cat .dvc/config
-  ...
-  ['remote "myremote"']
-      url = ../../dvcstore
-  ...
+...
+['remote "myremote"']
+    url = ../../dvcstore
+...
 ```
 
 > Note that `../dvcstore` has been resolved relative to the `.dvc/` dir,
@@ -423,10 +427,10 @@ The <abbr>project</abbr>'s config file (`.dvc/config`) now looks like this:
 
 ```ini
 ['remote "myremote"']
-url = s3://mybucket/path
-region = us-east-2
+    url = s3://mybucket/path
+    region = us-east-2
 [core]
-remote = myremote
+    remote = myremote
 ```
 
 The list of remotes should now be:

content/docs/command-reference/remote/default.md

@@ -1,9 +1,7 @@
 # remote default
 
-Set/unset the default [data remote](/doc/command-reference/remote).
-
-> Depending on your remote storage type, you may also need `dvc remote modify`
-> to provide credentials and/or configure other remote parameters.
+Set/unset the default
+[remote storage](/doc/user-guide/data-management/remote-storage).
 
 ## Synopsis
 

content/docs/command-reference/remote/index.md

@@ -1,13 +1,15 @@
 # remote
 
-A set of commands to set up and manage data remotes:
+A set of commands to set up and manage [remote storage]:
 [add](/doc/command-reference/remote/add),
 [default](/doc/command-reference/remote/default),
 [list](/doc/command-reference/remote/list),
 [modify](/doc/command-reference/remote/modify),
 [remove](/doc/command-reference/remote/remove), and
 [rename](/doc/command-reference/remote/rename).
 
+[remote storage]: /doc/user-guide/data-management/remote-storage
+
 ## Synopsis
 
 ```usage
@@ -101,9 +103,9 @@ The <abbr>project</abbr>'s config file should now look like this:
 
 ```ini
 ['remote "myremote"']
-url = /path/to/remote
+    url = /path/to/remote
 [core]
-remote = myremote
+    remote = myremote
 ```
 
 ## Example: List all remotes in the project
@@ -128,12 +130,12 @@ The project's config file should now look something like this:
 
 ```ini
 ['remote "myremote"']
-url = /path/to/remote
+    url = /path/to/remote
 [core]
-remote = myremote
+    remote = myremote
 ['remote "newremote"']
-url = s3://mybucket/path
-endpointurl = https://object-storage.example.com
+    url = s3://mybucket/path
+    endpointurl = https://object-storage.example.com
 ```
 
 ## Example: Change the name of a remote

content/docs/command-reference/remote/list.md

@@ -1,6 +1,7 @@
 # remote list
 
-List all available [data remotes](/doc/command-reference/remote).
+List all available
+[DVC remotes](/doc/user-guide/data-management/remote-storage).
 
 ## Synopsis
 

content/docs/command-reference/remote/modify.md

@@ -1,10 +1,14 @@
 # remote modify
 
-Modify the configuration of a [data remote](/doc/command-reference/remote).
+Configure a [DVC remote](/doc/user-guide/data-management/remote-storage).
 
-> This command is commonly needed after `dvc remote add` or
-> [default](/doc/command-reference/remote/default) to set up credentials or
-> other customizations to each remote storage type.
+<admon type="tip">
+
+This command is commonly needed after `dvc remote add` or `dvc remote default`
+to set up credentials or for other customizations specific to the
+[storage type](#available-parameters-per-storage-type).
+
+</admon>
 
 ## Synopsis
 
@@ -1197,10 +1201,10 @@ Now the project config file should look like this:
 
 ```ini
 ['remote "myremote"']
-url = s3://mybucket/path
-profile = myuser
+    url = s3://mybucket/path
+    profile = myuser
 [core]
-remote = myremote
+    remote = myremote
 ```
 
 ## Example: Some Azure authentication methods

content/docs/command-reference/remote/remove.md

@@ -1,8 +1,13 @@
 # remote remove
 
-Remove a [data remote](/doc/command-reference/remote). This command affects DVC
-configuration files only, it does not physically remove data files stored
-remotely.
+Remove a [DVC remote](/doc/user-guide/data-management/remote-storage).
+
+<admon type="info">
+
+This command affects DVC configuration files only. It does not physically remove
+data files stored remotely. See `dvc gc --cloud` for that.
+
+</admon>
 
 ## Synopsis
 

content/docs/command-reference/remote/rename.md

@@ -1,7 +1,12 @@
 # remote rename
 
-Rename a [data remote](/doc/command-reference/remote). The remote's URL is not
-changed by this command.
+Rename a [DVC remote](/doc/user-guide/data-management/remote-storage).
+
+<admon type="info">
+
+The remote storage URL is not changed by this command.
+
+</admon>
 
 ## Synopsis
 

content/docs/sidebar.json

@@ -122,8 +122,10 @@
       },
       {
         "slug": "data-management",
-        "source": false,
+        "source": "data-management/index.md",
         "children": [
+          "data-versioning",
+          "remote-storage",
           "large-dataset-optimization",
           "importing-external-data",
           "managing-external-data"

content/docs/user-guide/data-management/data-versioning.md

@@ -0,0 +1,70 @@
+# Data Versioning
+
+DVC enables [version control] for data science. But DVC does not actually
+implement versioning directly! Instead, DVC focuses on [codifying your data]:
+generating small [metafiles] that you can handle with standard [Git workflows]
+(commits, branching, pull requests, etc.).
+
+The resulting projects are neatly organized in the "space dimension", having
+only the files and directories needed at the time and without complicated, ad
+hoc file names like `2022-10-20_linear-model_v2-Carl`. Project versions live in
+the "time dimension" ([Git history]).
+
+![Versioned ML project](/img/versioned-project.png) _Navigate versions with Git
+commits_
+
+**Data version control** is the unifying trait across DVC features (data
+management and beyond).
+
+<admon icon="book">
+
+Refer to [Versioning Data and Models] to learn more.
+
+[versioning data and models]: /doc/use-cases/versioning-data-and-models
+
+</admon>
+
+[version control]:
+  https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control
+[codifying your data]: /doc/use-cases/versioning-data-and-models
+[metafiles]: /doc/user-guide/project-structure
+[git workflows]: https://www.atlassian.com/git/tutorials/comparing-workflows
+[git history]:
+  https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History
+
+<!--
+## Cloud versioning
+
+_New in DVC 2.30.0 (see `dvc version`)_
+
+To simplify remote data operations, DVC now supports native versioning of files
+and directories on several cloud providers. This means that you can browse your
+files normally as you would see them in your local workspace.
+-->
+
+## Project configuration
+
+Besides metafiles, <abbr>DVC projects</abbr> may contain a config file
+(`.dvc/config`) that can also be treated as code when it comes to version
+control.
+
+<admon icon="book">
+
+See `dvc config` for more information on DVC config.
+
+</admon>
+
+Some times it's important to version configuration changes along with
+corresponding data updates. Most notably, if you [set up remote storage] and
+`dvc push` data for others to `dvc pull` later, you should `git commit` both the
+metafile(s) and `.dvc/config` to the repo.
+
+Advanced situations where this may also be necessary:
+
+- When migrating to a [shared cache]
+- If you change a `dvc config parsing` option, which impact how `dvc.yaml` files
+  get parsed.
+
+[set up remote storage]:
+  /doc/user-guide/data-management/remote-storage#configuration
+[shared cache]: doc/user-guide/how-to/share-a-dvc-cache

content/docs/user-guide/data-management/index.md

@@ -0,0 +1,39 @@
+# Data Management with DVC
+
+DVC helps you manage and share arbitrarily large files, datasets, and ML models
+anywhere: cloud storage, SSH servers, network resources (e.g. NAS), mounted
+drives, local file systems, etc. You manipulate DVC project normally in your
+local workspace; DVC tracks, restores, and synchronizes them across locations.
+
+![Storage locations](/img/storage-locations.png) _Local, external, and remote
+storage locations_
+
+Every <abbr>DVC project</abbr> starts with 2 locations. The
+<abbr>workspace</abbr> is the main project directory, containing your data,
+models, source code, etc. DVC also creates a <abbr>data cache</abbr> (found
+locally in `.dvc/cache` by default), which will be used as fast-access storage
+for DVC operations.
+
+<admon type="tip">
+
+The cache can be moved to an external location in the file system or network,
+for example to [share it] among several projects. It could even be set up in a
+remote system (Internet access), but this is typically too slow for working with
+data regularly.
+
+</admon>
+
+[share it]: /doc/user-guide/how-to/share-a-dvc-cache
+
+Optionally, DVC supports additional storage locations such as cloud services
+(Amazon S3, Google Drive, Azure Blob Storage, etc.), SSH servers,
+network-attached storage, etc. These are called [DVC remotes], and help you to
+share or back up copies of your data assets.
+
+<admon type="info">
+
+DVC remotes are similar to Git remotes, but for <abbr>cached</abbr> data.
+
+</admon>
+
+[dvc remotes]: /doc/user-guide/data-management/remote-storage