cmd-ref: document --rev option on update

public/static/docs/command-reference/import.md

@@ -62,8 +62,7 @@ To actually [track the data](https://dvc.org/doc/get-started/add-files),
 `git add` (and `git commit`) the import stage.
 
 Note that import stages are considered always locked, meaning that if you run
-`dvc repro`, they won't be updated. Use `dvc update` or
-[re-import](#example-fixed-revisions-re-importing) them to update the downloaded
+`dvc repro`, they won't be updated. Use `dvc update` to update the downloaded
 data artifact from the source repo.
 
 ## Options
@@ -130,7 +129,7 @@ Several of the values above are pulled from the original stage file
 subfields under `repo` are used to save the origin and version of the
 dependency, respectively.
 
-## Example: Fixed revisions & re-importing
+## Example: Fixed revisions and updating to different revision
 
 To import a specific version of a <abbr>data artifact</abbr>, we may use the
 `--rev` option:
@@ -160,22 +159,9 @@ deps:
 If `rev` is a Git branch or tag (where the underlying commit changes), the data
 source may have updates at a later time. To bring it up to date if so (and
 update `rev_lock` in the DVC-file), simply use `dvc update <stage>.dvc`. If
-`rev` is a specific commit hash (does not change), `dvc update` will never have
-an effect on the import stage. You may **re-import** a different commit instead,
-by using `dvc import` again with a different (or without) `--rev`. For example:
-
-```dvc
-$ dvc import --rev master \
-             [email protected]:iterative/dataset-registry.git \
-             use-cases/cats-dogs
-```
-
-The import stage is overwritten, and will now be able update normally with
-`dvc update`.
-
-> In the above example, the value for `rev` in the new import stage will be
-> `master` (default branch), so the command is equivalent to not using `--rev`
-> at all.
+`rev` is a specific commit (does not change), `dvc update` will never have an
+effect on the import stage. You may `dvc update` to a different commit, using
+`--rev`.
 
 ## Example: Data registry
 

public/static/docs/command-reference/update.md

@@ -6,7 +6,7 @@ projects</abbr>, and corresponding [DVC-files](/doc/user-guide/dvc-file-format).
 ## Synopsis
 
 ```usage
-usage: dvc update [-h] [-q | -v] targets [targets ...]
+usage: dvc update [-h] [-q | -v] [--rev [REV]] targets [targets ...]
 
 positional arguments:
   targets        DVC-files to update.
@@ -27,20 +27,32 @@ Note that import stages are considered always locked, meaning that if you run
 update them.
 
 `dvc update` will not have an effect on import stages that are fixed to a commit
-hash (`rev` field in the DVC-file). Please refer to
-[Fixed revisions & re-importing](/doc/command-reference/import#example-fixed-revisions-re-importing)
-for more details.
+hash (`rev` field in the DVC-file). To update the imported artifacts to a
+certain revision, `--rev` with specified revision can be used.
+
+```dvc
+dvc update --rev master
+```
 
 ## Options
 
+- `--rev` - specific
+  [Git revision](https://git-scm.com/book/en/v2/Git-Internals-Git-References)
+  (such as a branch name, a tag, or a commit hash) of the repository to update
+  the file or directory from (also starts tracking the given revision).
+
+  > Note that this adds or updates a `rev` field in the DVC-file that fixes it
+  > to this revision (and updates `rev_lock` in the DVC-file). This can have an
+  > impact on the behavior of `dvc update` later.
+
 - `-h`, `--help` - prints the usage/help message, and exit.
 
 - `-q`, `--quiet` - do not write anything to standard output. Exit with 0 if no
   problems arise, otherwise 1.
 
 - `-v`, `--verbose` - displays detailed tracing information.
 
-## Examples
+## Example: Updating imported artifacts
 
 Let's first import a data artifact from our
 [get started example repo](https://github.com/iterative/example-get-started):
@@ -69,3 +81,42 @@ stable.
 > Note that `dvc update` updates the `rev_lock` field of the corresponding
 > [DVC-file](/doc/user-guide/dvc-file-format) (when there are changes to bring
 > in).
+
+## Example: Updating imported artifacts to a specified revision
+
+Let's import a data artifact from an older commit from our
+[get started example repo](https://github.com/iterative/example-get-started) at
+first:
+
+```dvc
+$ dvc import --rev baseline-experiment [email protected]:iterative/example-get-started model.pkl
+Importing 'model.pkl ([email protected]:iterative/example-get-started)'
+-> 'model.pkl'
+```
+
+After this, the import stage (DVC-file) `model.pkl.dvc` is created.
+
+Let's try to run `dvc update` on the given stage file, and see what happens.
+
+```dvc
+$ dvc update model.pkl.dvc
+```
+
+There was no output at all, meaning, the `model.pkl` file was not updated. This
+is because, we tied the import stage with a `rev` that never changes (i.e. tag
+is tied to a specific commit). Therefore, it was not updated.
+
+Let's try to update the model to a different experiment `bigrams-experiment`.
+
+```dvc
+$ dvc update --rev bigrams-experiment model.pkl.dvc
+WARNING: DVC-file 'model.pkl.dvc' changed.
+WARNING: Stage 'model.pkl.dvc' changed.
+Importing 'model.pkl ([email protected]:iterative/example-get-started)' -> 'model.pkl'
+```
+
+The import stage is overwritten, and will get updated from the latest changes in
+the given revision(i.e. `bigrams-experiment` tag).
+
+> In the above example, the value for `rev` in the new import stage will be
+> `bigrams-experiment`.