From eb07a3cf2ad4276a630dc6a396c9a902881ad6c9 Mon Sep 17 00:00:00 2001 From: Saugat Pachhai Date: Tue, 18 Feb 2020 17:02:56 +0545 Subject: [PATCH] cmd-ref: document --rev option on update --- .../static/docs/command-reference/import.md | 24 ++------ .../static/docs/command-reference/update.md | 61 +++++++++++++++++-- 2 files changed, 61 insertions(+), 24 deletions(-) diff --git a/public/static/docs/command-reference/import.md b/public/static/docs/command-reference/import.md index b97bf79a57..460a7241be 100644 --- a/public/static/docs/command-reference/import.md +++ b/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 data artifact, 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 .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 \ - git@github.com: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 diff --git a/public/static/docs/command-reference/update.md b/public/static/docs/command-reference/update.md index 630c342867..ed79e97cb4 100644 --- a/public/static/docs/command-reference/update.md +++ b/public/static/docs/command-reference/update.md @@ -6,7 +6,7 @@ projects, 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,12 +27,24 @@ 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 @@ -40,7 +52,7 @@ for more details. - `-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 git@github.com:iterative/example-get-started model.pkl +Importing 'model.pkl (git@github.com: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 (git@github.com: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`.