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

skshetry · 2020-02-18T11:19:49Z

You may disregard these recommendations if you used the Edit on GitHub button from dvc.org to improve a doc in place.

❗ Please read the guidelines in the Contributing to the Documentation list if you make any substantial changes to the documentation or JS engine.

🐛 Please make sure to mention Fix #issue (if applicable) in the description of the PR. This causes GitHub to close it automatically when the PR is merged.

Please chose to allow us to edit your branch when creating the PR.

Thank you for the contribution - we'll try to review it as soon as possible. 🙏

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

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

shcheklein · 2020-02-18T16:13:39Z

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

+
+```dvc
+$ dvc import --rev 72e0f1 [email protected]:iterative/example-get-started model.pkl
+Importing 'model.pkl ([email protected]:iterative/example-get-started)'


no need to include obvious outputs

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

shcheklein · 2020-02-18T16:16:54Z

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

+branch.
+
+```dvc
+$ dvc update --rev master model.pkl.dvc


let's try to not change semantics - from fixed commit to not following the branch

Do you have any good examples in mind? I'm using this as a kind of a hack for being short of examples. I tried using the recent aita_dataset but, the dataset on master was too large (~117 MB) just for the demonstration (but, it's quite good in that I can change the --rev from master to lightweight, quite good example really).

we can use tags at least? there are two tags in the example-get-started - baseline-experiment and bigrams-experiment

tags are more or less static, and you have to use re-import or use dvc update --rev to move the latest version

what do you think?

@shcheklein, i moved to tags. Showing example of moving between experiments is good, but I feel, importing from a fixed revision and trying to move to a recent version of artifacts is also a good example worth showing off.

@skshetry agreed, but we need a bit different approach then (we can't rely on a specific hash since it might change). Git clone repo use git to take the latest hash? (basically show how to take it?) .... or even use dvc list - may be a good idea for the list to show commit hashes?

Seems like a similar question as #1007 (comment):

It's baiscaly the same as Example: Fixed revisions and updating to different revision in dvc import. Maybe we should just copy/paste it...

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

shcheklein

Good stuff @skshetry ! Please take a look at the comments - if you know how to address them - please do, otherwise we'll take of the PR eventually.

shcheklein · 2020-02-28T06:29:34Z

@jorgeorpinel I think this like 10 days already? I think it's perfect to merge. Could you just take a brief look, address minor changes if you see them and let's merge?

shcheklein · 2020-02-29T02:57:48Z

@jorgeorpinel merging this, let's address what's left (if anything) as a regular update.

jorgeorpinel · 2020-03-02T19:02:02Z

Sorry for the delay. I'm just getting to this now. Will note any comments here but we'll have to address in a separate PR of course.

jorgeorpinel

Review post-merge. @skshetry are you willing/able to give it another pass? Thanks

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

jorgeorpinel · 2020-03-02T23:34:08Z

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

-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.


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.

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

jorgeorpinel · 2020-03-02T23:34:18Z

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

+- `--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.


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.)

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

jorgeorpinel · 2020-03-02T23:57:20Z

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

+```
+
+The import stage is overwritten, and will get updated from the latest changes in
+the given revision (i.e. `bigrams-experiment` tag).


given commit (tag `bigrams-experiment)

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

skshetry · 2020-03-03T04:37:04Z

@jorgeorpinel, I'll work on it later today. Thanks for the review.

jorgeorpinel · 2020-03-03T16:58:51Z

Thank you!

per #1007 (review)

skshetry requested review from jorgeorpinel and shcheklein February 18, 2020 11:19

skshetry self-assigned this Feb 18, 2020

shcheklein temporarily deployed to dvc-landing-doc-update-laonfvd February 18, 2020 11:19 Inactive

skshetry force-pushed the doc-update-rev branch from da40ffd to 4cc57eb Compare February 18, 2020 11:21

shcheklein temporarily deployed to dvc-landing-doc-update-laonfvd February 18, 2020 11:21 Inactive

shcheklein reviewed Feb 18, 2020

View reviewed changes

public/static/docs/command-reference/import.md Outdated Show resolved Hide resolved

shcheklein reviewed Feb 18, 2020

View reviewed changes

public/static/docs/command-reference/update.md Outdated Show resolved Hide resolved

shcheklein reviewed Feb 18, 2020

View reviewed changes

public/static/docs/command-reference/update.md Outdated Show resolved Hide resolved

shcheklein reviewed Feb 18, 2020

View reviewed changes

public/static/docs/command-reference/update.md Show resolved Hide resolved

shcheklein requested changes Feb 18, 2020

View reviewed changes

cmd-ref: document --rev option on update

eb07a3c

skshetry force-pushed the doc-update-rev branch from 4cc57eb to eb07a3c Compare February 20, 2020 15:21

shcheklein temporarily deployed to dvc-landing-doc-update-laonfvd February 20, 2020 15:22 Inactive

weekly-digest bot mentioned this pull request Feb 23, 2020

Weekly Digest (16 February, 2020 - 23 February, 2020) #1015

Closed

shcheklein assigned shcheklein and unassigned skshetry Feb 28, 2020

minor: cosmetic changes

9ac4006

shcheklein merged commit 881af3f into master Feb 29, 2020

skshetry deleted the doc-update-rev branch February 29, 2020 03:05

weekly-digest bot mentioned this pull request Mar 1, 2020

Weekly Digest (23 February, 2020 - 1 March, 2020) #1031

Closed

jorgeorpinel reviewed Mar 2, 2020

View reviewed changes

skshetry mentioned this pull request Mar 17, 2020

cmd-ref: address reviews from #1007 #1062

Closed

2 tasks

jorgeorpinel added a commit that referenced this pull request Apr 7, 2020

cmd ref: small pending improvements from recent import/update changes

f8789da

per #1007 (review)

jorgeorpinel mentioned this pull request Apr 7, 2020

cmd-ref: make changes related to update --rev #1090

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

skshetry commented Feb 18, 2020

shcheklein Feb 18, 2020

This comment was marked as resolved.

shcheklein Feb 18, 2020

skshetry Feb 18, 2020 •

edited

Loading

shcheklein Feb 18, 2020

shcheklein Feb 18, 2020

skshetry Feb 20, 2020 •

edited

Loading

shcheklein Feb 20, 2020

jorgeorpinel Mar 3, 2020

shcheklein left a comment

shcheklein commented Feb 28, 2020

shcheklein commented Feb 29, 2020

jorgeorpinel commented Mar 2, 2020 •

edited

Loading

jorgeorpinel left a comment

jorgeorpinel Mar 2, 2020

jorgeorpinel Mar 2, 2020

jorgeorpinel Mar 2, 2020

skshetry commented Mar 3, 2020

jorgeorpinel commented Mar 3, 2020

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

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

Conversation

skshetry commented Feb 18, 2020

Choose a reason for hiding this comment

This comment was marked as resolved.

Choose a reason for hiding this comment

skshetry Feb 18, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

skshetry Feb 20, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shcheklein left a comment

Choose a reason for hiding this comment

shcheklein commented Feb 28, 2020

shcheklein commented Feb 29, 2020

jorgeorpinel commented Mar 2, 2020 • edited Loading

jorgeorpinel left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

skshetry commented Mar 3, 2020

jorgeorpinel commented Mar 3, 2020

skshetry Feb 18, 2020 •

edited

Loading

skshetry Feb 20, 2020 •

edited

Loading

jorgeorpinel commented Mar 2, 2020 •

edited

Loading