Document --backup import behaviour

content/docs/command-reference/import.md

@@ -10,7 +10,9 @@ the import.
 ## Synopsis
 
 ```usage
-usage: dvc import [-h] [-q | -v] [-o <path>] [--rev <commit>] url path
+usage: dvc import [-h] [-q | -v]
+                  [-o <path>] [--file <filename>] [--rev <commit>] [--store]
+                  url path
 
 positional arguments:
   url              Location of DVC or Git repository to download from
@@ -74,6 +76,25 @@ Note that import stages are considered always
 they won't be updated. Use `dvc update` to update the downloaded data artifact
 from the source repo.
 
+### Enabling remote storage
+
+To avoid duplicating large files, imported data is not pushed to
+[remote storage](/doc/command-reference/remote) by default (see `dvc push`).
+This means that `dvc pull`, `dvc fetch`, and `dvc repro` retrieve imports from
+their source (found in the `deps` field of the `.dvc` file). So if the original
+source of an import is deleted, then the files are not backed up anywhere, and
+data may be lost.
+
+As an alternative, you can use the `--store` option so the import is pushed to a
+DVC remote when `dvc push` is run. This also means that `dvc pull/fetch/repro`
+no longer access import sources, going to the remote instead, like with regular
+project data tracked with `dvc add`. You can still use `dvc update` to get the
+latest import data from its source.
+
+Remote storage is enabled with a `store: true` key/value pair in the `outs`
+section of the import `.dvc` file. To switch to regular import behavior, change
+its value to `false` manually, or re-import the data without the `--store` option.
+
 ## Options
 
 - `-o <path>`, `--out <path>` - specify a path to the desired location in the
@@ -91,6 +112,10 @@ from the source repo.
   > [Importing and updating fixed revisions](#example-importing-and-updating-fixed-revisions)
   > example below).
 
+- `-s`, `--store` - [enables remote storage](#enabling-remote-storage) for the
+  import, so it can be pushed and pulled like regular project data (e.g. in
+  case the original source is lost).
+
 - `-h`, `--help` - prints the usage/help message, and exit.
 
 - `-q`, `--quiet` - do not write anything to standard output. Exit with 0 if no

content/docs/user-guide/dvc-files-and-directories.md

@@ -71,6 +71,10 @@ An _output entry_ (`outs`) consists of these fields:
   _checksum_ for HDFS.
 - `cache`: Whether or not this file or directory is <abbr>cached</abbr> (`true`
   by default, if not present). See the `--no-commit` option of `dvc add`.
+- `store`: Whether or not this file or directory is pushed and pulled to/from
+  [remote storage](/doc/command-reference/remote) (`true` by default for all
+  outputs except for imports, where it is `false` by default). See
+  [import storage](/doc/command-reference/import#enabling-remote-storage).
 
 A _dependency entry_ (`deps`) consists of these fields:
 

content/docs/user-guide/troubleshooting.md

@@ -53,3 +53,16 @@ Unable to detect supported link types, as the
 [cache directory](/doc/command-reference/config#cache) doesn't exist. It is
 usually created automatically by DVC commands that need it, but you can create
 it manually (e.g. `mkdir .dvc/cache`) to enable this check.
+
+## Checkout failed with `store: false` files {#checkout-failed-no-store}
+
+Unable to checkout this output since it is not present in the cache and has been
+marked to not be stored on remotes.
+
+If `store: false` is added to the `outs` section of a `.dvc` file, that output
+will not be stored on remotes when `dvc push` is used, and dvc will not attempt
+to retreive it when `dvc pull` or `dvc fetch` is called. This error means that
+the file is not already in the local cache, so dvc cannot find it. You must
+provide the file locally since it is not tracked on dvc-managed remote storage.
+
+See [import storage](/doc/command-reference/import#enabling-remote-storage).