cmd ref: freeze/unfreeze 1.0 and improvements (#1493)

* cmd ref: add more explanations to freeze per #1488 (review) et al. * cmd ref: more updates to freeze * cmd ref: updates to unfreeze based on those to freeze see recent commits * cmd ref: revise examples of (un)freeze refs. * cmd: fix examples in (un)freeze per #1493 (review) * cmd: rewrite intros to (un)freeze per #1493 (review)
iterative · Jun 25, 2020 · 87e83e1 · 87e83e1
1 parent b347211
commit 87e83e1
Show file tree

Hide file tree

Showing 2 changed files with 56 additions and 78 deletions.
diff --git a/content/docs/command-reference/freeze.md b/content/docs/command-reference/freeze.md
@@ -1,32 +1,32 @@
 # freeze
 
-Freeze a [stage](/doc/command-reference/run). Use `dvc unfreeze` to unfreeze the
-stage.
+Freeze [stages](/doc/command-reference/run) until `dvc unfreeze` is used on
+them. Frozen stages are never executed by `dvc repro`.
 
 ## Synopsis
 
 ```usage
 usage: dvc freeze [-h] [-q | -v] targets [targets ...]
 
 positional arguments:
-  targets        stages to freeze.
+  targets        Stages or .dvc files to freeze
 ```
 
 ## Description
 
-`dvc freeze` causes any stage to be considered _not changed_ by `dvc status` and
-`dvc repro`. Stage reproduction will not regenerate <abbr>outputs</abbr> of
-frozen stages, even if some dependencies have changed, and even if `--force` is
-provided.
+`dvc freeze` causes the [stages](/doc/command-reference/run) indicated as
+`targets` to be considered _not changed_ by `dvc status` and `dvc repro`. Stage
+reproduction will not regenerate <abbr>outputs</abbr> of frozen stages, even if
+their <abbr>dependencies</abbr> have changed, and even if `--force` is used.
 
 Freezing a stage is useful to avoid syncing data from the top of its
 [pipeline](/doc/command-reference/pipeline), and keep iterating on the last
-(unfrozen) stages only.
+(non-frozen) stages only.
 
-Note that <abbr>import stages</abbr> are considered always frozen. Use
-`dvc update` to update the corresponding <abbr>data artifacts</abbr> from the
-external data source. [Unfreeze](/doc/command-reference/unfreeze) them before
-using `dvc repro` on a pipeline that needs their outputs.
+Note that <abbr>import stages</abbr> are frozen by default. Use `dvc update` to
+update the corresponding <abbr>data artifacts</abbr> from the external data
+source. [Unfreeze](/doc/command-reference/unfreeze) them before using
+`dvc repro` on a pipeline that needs their outputs.
 
 ## Options
 
@@ -39,21 +39,21 @@ using `dvc repro` on a pipeline that needs their outputs.
 
 ## Examples
 
-First, let's create a simple DVC-file:
+First, let's create a dummy stage that copies `foo` to `bar`:
 
 ```dvc
 $ echo foo > foo
 $ dvc add foo
-$ dvc run -d foo -o bar -n make_copy cp foo bar
+$ dvc run -n make_copy -d foo -o bar cp foo bar
 ```
 
+> See `dvc run` for more details.
+
 Then, let's change the file `foo` that the stage `make_copy` depends on:
 
 ```dvc
-$ rm foo
-$ echo foo1 > foo
+$ echo zoo > foo
 $ dvc status
-
 make_copy:
 	changed deps:
 		modified:           foo
@@ -62,27 +62,19 @@ foo.dvc:
 		modified:           foo
 ```
 
-Now, let's freeze the `make_copy` stage:
+`dvc status` notices that `foo` has changed. Let's now freeze the `make_copy`
+stage and see what's the project status after that:
 
 ```dvc
 $ dvc freeze make_copy
 $ dvc status
-
 foo.dvc:
 	changed outs:
 		modified:           foo
 ```
 
-Run `dvc unfreeze` to unfreeze it back:
+DVC notices that `foo` changed due to the `foo.dvc` file that tracks this file
+(as `outs`), but the `make_copy` stage no longer records the change among it's
+`deps`.
 
-```dvc
-$ dvc unfreeze make_copy
-$ dvc status
-
-make_copy:
-	changed deps:
-		modified:           foo
-foo.dvc:
-	changed outs:
-		modified:           foo
-```
+> You can use `dvc unfreeze` to go back to the regular project status.
diff --git a/content/docs/command-reference/unfreeze.md b/content/docs/command-reference/unfreeze.md
@@ -1,28 +1,31 @@
 # unfreeze
 
-Unfreeze [stage](/doc/command-reference/run). See `dvc freeze` for more
-information.
+Unfreeze [stages](/doc/command-reference/run) so that `dvc repro` can execute
+them. See `dvc freeze` for more information.
 
 ## Synopsis
 
 ```usage
 usage: dvc unfreeze [-h] [-q | -v] targets [targets ...]
 
 positional arguments:
-  targets        stages to unfreeze.
+  targets        Stages or .dvc files to unfreeze
+                 (see also `dvc freeze`).
 ```
 
 ## Description
 
-There are several reasons that can produce data files to be frozen in a DVC
-project, `dvc freeze` being the most obvious one.
+There are several ways that tracked data files can be frozen, `dvc freeze` being
+one of them. Frozen stages are considered _not changed_ by `dvc status` and
+`dvc repro`.
 
-If `dvc unfreeze` is used on frozen stages, they will start to be checked by
-`dvc status`, and updated by `dvc repro`.
+If `dvc unfreeze` is used on frozen stages, they will start being checked again
+by `dvc status`, and regenerated by `dvc repro`.
 
-Note that <abbr>import stages</abbr> are considered always frozen. They can not
-be unfrozen. Use `dvc update` on them to update the file, directory, or
-<abbr>data artifact</abbr> from its external data source.
+Note that <abbr>import stages</abbr> are frozen by default. Use `dvc update` to
+update the corresponding <abbr>data artifacts</abbr> from the external data
+source. [Unfreeze](/doc/command-reference/unfreeze) them before using
+`dvc repro` on a pipeline that needs their outputs.
 
 ## Options
 
@@ -35,56 +38,39 @@ be unfrozen. Use `dvc update` on them to update the file, directory, or
 
 ## Examples
 
-First, let's create a simple DVC-file:
+First, let's create a dummy stage that copies `foo` to `bar`:
 
 ```dvc
 $ echo foo > foo
 $ dvc add foo
-Saving information ...
-
-$ dvc run -d foo -o bar cp foo bar
-Running command:
-  cp foo bar
-...
+$ dvc run -n make_copy -d foo -o bar cp foo bar
 ```
 
-Then, let's change the file `foo` that the stage described in `bar.dvc` depends
-on:
-
-```dvc
-$ rm foo
-$ echo foo1 > foo
-$ dvc status
-
-bar.dvc
-        deps
-                changed:  foo
-foo.dvc
-        outs
-                changed:  foo
-```
+> See `dvc run` for more details.
 
-Now, let's freeze the `bar` stage:
+Then, let's change the file `foo` that the stage `make_copy` depends on, and
+freeze stage as well, to see what's the project status after that:
 
 ```dvc
-$ dvc freeze bar.dvc
+$ echo zoo > foo
+$ dvc freeze make_copy
 $ dvc status
-
-  foo.dvc
-          outs
-                  changed:  foo
+foo.dvc:
+	changed outs:
+		modified:           foo
 ```
 
-Run `dvc unfreeze` to unfreeze it back:
+DVC notices that `foo` changed due to the `foo.dvc` file that tracks this file
+(as `outs`), but the `make_copy` stage doesn't records the change among it's
+dependencies. Run `dvc unfreeze` to get the regular/full project status:
 
 ```dvc
-$ dvc unfreeze bar.dvc
+$ dvc unfreeze make_copy
 $ dvc status
-
-  bar.dvc
-          deps
-                  changed:  foo
-  foo.dvc
-          outs
-                  changed:  foo
+make_copy:
+	changed deps:
+		modified:           foo
+foo.dvc:
+	changed outs:
+		modified:           foo
 ```