Skip to content

cmd-ref: document --rev option on update #1007

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
shcheklein merged 2 commits into from
Feb 29, 2020
Merged

cmd-ref: document --rev option on update #1007

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
eb07a3c
cmd-ref: document --rev option on update
skshetry Feb 18, 2020
9ac4006
minor: cosmetic changes
shcheklein Feb 28, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 6 additions & 16 deletions public/static/docs/command-reference/import.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -160,23 +159,14 @@ 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:
`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`:

```dvc
$ dvc import --rev master \
git@github.com:iterative/dataset-registry.git \
use-cases/cats-dogs
$ dvc update --rev cats-dogs-v2
```

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.
Comment on lines -173 to -178
Copy link
Contributor

@jorgeorpinel jorgeorpinel Mar 2, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This info is still useful if using --rev master above, just a little different:

> In the above example, the value for `rev` in the new import stage will be
> `master` (a branch) so it will be able update normally going forward.


## Example: Data registry

If you take a look at our
Expand Down
60 changes: 55 additions & 5 deletions public/static/docs/command-reference/update.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Comment on lines +39 to +46
Copy link
Contributor

@jorgeorpinel jorgeorpinel Mar 2, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lets just copy this from import:

Suggested change
- `--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.
- `--rev` - commit hash, branch or tag name, etc. (any
[Git revision](https://git-scm.com/docs/revisions)) of the repository to
update the file or directory from. The latest commit in `master` (tip of the
default branch) is used by default when this option is not specified.
> Note that this adds a `rev` field in the import stage that fixes it to this
> revision. This can impact the behavior of `dvc update`. (See
> **re-importing** example below.)


- `-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):
Expand Down Expand Up @@ -69,3 +81,41 @@ 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
Copy link
Contributor

@jorgeorpinel jorgeorpinel Mar 2, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## Example: Updating imported artifacts to a specified revision
## Example: Updating fixed-revision imports to a different version

And explain what fixed revision is in the first p. Again, maybe just copy the example from dvc import?


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)'
Copy link
Contributor

@shcheklein shcheklein Feb 18, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no need to include obvious outputs

This comment was marked as resolved.

Sign in to view

-> '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
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).
Copy link
Contributor

@jorgeorpinel jorgeorpinel Mar 2, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

given commit (tag `bigrams-experiment)


> In the above example, the value for `rev` in the new import stage will be
> `bigrams-experiment`.
2 changes: 1 addition & 1 deletion public/static/docs/use-cases/data-registries.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,7 @@ $ dvc update dataset.dvc
`images/faces/`, based on the latest commit in the source repo. It also updates
the project dependency metadata in the import stage (DVC-file).

### Programatic reusability of DVC data
### Programmatic reusability of DVC data

Our Python API, included with the `dvc` package installed with DVC, includes the
`open` function to load/stream data directly from external <abbr>DVC
Expand Down