From 5b7cd573839804ca06ef60624049b9b522ae793e Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Tue, 2 Feb 2021 04:33:52 -0600 Subject: [PATCH] guide: complete output entry info for dvc.lock per https://github.com/iterative/dvc.org/pull/2131#pullrequestreview-580988405 --- .../project-structure/pipelines-files.md | 21 ++++++++++++------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/content/docs/user-guide/project-structure/pipelines-files.md b/content/docs/user-guide/project-structure/pipelines-files.md index db56a0879c..b68092612c 100644 --- a/content/docs/user-guide/project-structure/pipelines-files.md +++ b/content/docs/user-guide/project-structure/pipelines-files.md @@ -344,7 +344,7 @@ stages: | `cmd` | (Required) One or more commands executed by the stage (may contain either a single value or a list). Commands are executed sequentially until all are finished or until one of them fails (see `dvc repro`). | | `wdir` | Working directory for the stage command to run in (relative to the file's location). Any paths in other fields are also based on this. It defaults to `.` (the file's location). | | `deps` | List of dependency paths of this stage (relative to `wdir`). | -| `outs` | List of output paths of this stage (relative to `wdir`). See [Output entries](#output-entries) for more details. | +| `outs` | List of output paths of this stage (relative to `wdir`). See [Simple output entries](#simple-output-entries) for more details. | | `params` | List of parameter dependency keys (field names) to track from `params.yaml` (in `wdir`). The list may also contain other parameters file names, with a sub-list of the param names to track in them. | | `metrics` | List of [metrics files](/doc/command-reference/metrics), and optionally, whether or not this metrics file is cached (`true` by default). See the `--metrics-no-cache` (`-M`) option of `dvc run`. | | `plots` | List of [plot metrics](/doc/command-reference/plots), and optionally, their default configuration (subfields matching the options of `dvc plots modify`), and whether or not this plots file is cached ( `true` by default). See the `--plots-no-cache` option of `dvc run`. | @@ -364,7 +364,11 @@ validation and auto-completion. > See also > [How to Merge Conflicts](/doc/user-guide/how-to/merge-conflicts#dvcyaml). -### Output entries +### Simple output entries + +> _Simple_ compared to full +> [output entries](/doc/user-guide/project-structure/dvc-files#output-entries) +> used in `dvc.lock` and `.dvc` files | Field | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------ | @@ -382,8 +386,8 @@ DVC will maintain a `dvc.lock` file for each `dvc.yaml`. Their purposes include: - Allow DVC to detect when stage definitions, or their dependencies have changed. Such conditions invalidate stages, requiring their reproduction (see `dvc status`). -- Tracking of intermediate and final outputs of a pipeline — - similar to `.dvc` files. +- Tracking of intermediate and final outputs of a pipeline — similar to `.dvc` + files. - Needed for several DVC commands to operate, such as `dvc checkout` or `dvc get`. @@ -415,12 +419,13 @@ stages: Stages are listed again in `dvc.lock`, in order to know if their definitions change in `dvc.yaml`. -Regular dependencies and all kinds of outputs +Full +[dependency entries](/doc/user-guide/project-structure/dvc-files#dependency-entries) +and all forms of +[output entries](/doc/user-guide/project-structure/dvc-files#output-entries) (including [metrics](/doc/command-reference/metrics) and [plots](/doc/command-reference/plots) files) are also listed (per stage) in -`dvc.lock`, but with an additional field storing a hash of their last known -contents. Specifically: `md5`, `etag`, or `checksum` are used (same as in `deps` -and `outs` entries of `.dvc` files). +`dvc.lock`, including a content hash field (`md5`, `etag`, or `checksum`). Full parameter dependencies (key and value) are listed too (under `params`), grouped by parameters file.