ref: `data status` updates #3924

jorgeorpinel · 2022-09-06T20:16:16Z

jorgeorpinel · 2022-09-06T20:20:53Z

content/docs/command-reference/data/status.md

-  `dvc-commit`-ed that differs with the last Git commit. There might be more
-  detailed state on how each of those files changed: _added_, _modified_,
-  _deleted_ and _unknown_.


One question though: what's an unknown change? Does it apply to untracked files too? I didn't know where to mention that in the updated text.

For example, let's say you clone a repo with a tracked directory but haven't done dvc fetch/pull. You have an md5 in the .dvc file but the directory is empty. If you modify the directory (for example, add a file to it), DVC can tell that the directory doesn't match the md5 but has no info about the granular changes to the files in that directory.

DVC can tell that the directory doesn't match the md5 but has no info about the granular changes to the files in that directory

So it only applies to --granular right? (Assuming that generalizing that example is the one scenario for this.) I added a note in that option instead of trying to cover it up here (it still counts as "new, modified, or deleted"). aca9d8a

@skshetry Do you know if it can ever apply to non-granular data?

yeah, it only applies to granular.

per #3812 (comment)

jorgeorpinel · 2022-09-06T20:25:49Z

There may be other things for you to include here based on pending comments under #3812 (comment) @dberenbaum

Thanks!

github-actions · 2022-09-06T20:27:16Z

Link Check Report

content/docs/command-reference/data/status.md
- FAIL: doc/user-guide/project-structure/internal-files#directories = https://doc/user-guide/project-structure/internal-files#directories (EAI_AGAIN: request to https://doc/user-guide/project-structure/internal-files#directories failed, reason: getaddrinfo EAI_AGAIN doc)
- PASS: /doc/command-reference/commit = https://dvc-org-ref-data-status-bnsygg.herokuapp.com/doc/command-reference/commit (200)
- PASS: /doc/command-reference/add#adding-entire-directories = https://dvc-org-ref-data-status-bnsygg.herokuapp.com/doc/command-reference/add#adding-entire-directories (200)

1/3 links failed.

content/docs/command-reference/data/status.md

shcheklein · 2022-09-06T20:33:39Z

content/docs/command-reference/data/status.md

@@ -83,31 +88,6 @@ option.

 - `-v`, `--verbose` - displays detailed tracing information.

-## Examples


why removing it?

I suggest removing it because it's already used in the description.

You asked me to make a PR with the most important changes from my feedback and IMO this is one of them: #3812 (comment).

#3812 (comment) - the problem is it was discussed already. Question - do you have an actually strong opinion about this? :) (I'm personally fine and Dave was fine it seems)

I didn't realize it had been discussed (I didn't read all the resolved comments). I still think it's unnecessary since the --granular example can still refer to the one in the description.

It's not a very strong opinion but it does go against good practices for cmd ref examples, I think: they should add special value to the doc, not just cover obvious cases. And to avoid redundancy in general.

But anyway, I rolled it back in 725c7e4 since it was discussed by them.

shcheklein

@jorgeorpinel we go into another round of discussions here I feel, again there are copy edits + substnatial product changes together. It makes review complicated.

jorgeorpinel

Per #3924 (review)

content/docs/command-reference/data/status.md

Co-authored-by: Restyled.io <[email protected]>

content/docs/command-reference/data/status.md

per #3924 (comment)

…ef/data-status

content/docs/command-reference/data/status.md

per #3924 (review)

content/docs/command-reference/data/status.md

skshetry · 2022-09-09T05:41:10Z

content/docs/command-reference/data/status.md

+  This may happen after cloning a DVC repository but before using `dvc pull` (or
+  `dvc fetch`) to download the data; or after using `dvc gc`.
+
+- _DVC committed changes_ are new, modified, or deleted tracked files or


Let's call it added to keep it in sync with the output.

Suggested change

- _DVC committed changes_ are new, modified, or deleted tracked files or

- _DVC committed changes_ are added, modified, or deleted tracked files or

Same on DVC uncommitted changes.

I'm not using back ticks because this doesn't intend to reflect the exact output. I think "added" is misleading and the output itself seems to be up for debate. Please see/ comment in iterative/dvc#7943 (review).

@jorgeorpinel It's a good point, but @skshetry also has a reasonable rationale for using "added," so what do you think about continuing discussion in another issue and leaving "added" to get this merged?

content/docs/command-reference/data/status.md

skshetry · 2022-09-09T05:45:12Z

content/docs/command-reference/data/status.md

@@ -1,6 +1,6 @@
 # data status

-Show changes in the data tracked by DVC in the workspace.
+Show changes to the files and directories tracked by DVC.


The command name is data. I am not sure what we get by replacing it.

We are specific about what we mean by data. Docs should explain 🙂

rel #3924 (review)

per #3924 (review)

jorgeorpinel · 2022-09-13T02:02:45Z

content/docs/command-reference/data/status.md

+  directories. Note that some granular changes may be reported as `unknown` as
+  DVC tracks
+  [directory-level hash values](doc/user-guide/project-structure/internal-files#directories).


I don't understand this comment tbh.
From aca9d8a#r83797370

Do you mean you're not familiar with the underlying situation this refers to @shcheklein? Please see #3924 (comment) if so. It's kind of confusing (maybe I didn't even get it right, waiting for another review from the core team).

Another alternative is to not even document this specifically, if it's evident what unknown means in the CLI output (self-documenting).

Suggested change

directories. Note that some granular changes may be reported as `unknown` as

DVC tracks

[directory-level hash values](doc/user-guide/project-structure/internal-files#directories).

directories.

I might understand this if read the comment (i haven't yet), but I would expect to be able to understand it from the text, right?

do you mean that some files (not granular changes) can be reported as "unknown" if (when? as DVC tracks is not informative)?

Yeah it's not that easy to explain briefly. How about this?

Suggested change

directories. Note that some granular changes may be reported as `unknown` as

DVC tracks

[directory-level hash values](doc/user-guide/project-structure/internal-files#directories).

directories. Note that granular changes may have "unknown" state if tracked

[directory contents](doc/user-guide/project-structure/internal-files#directories)

are not present in the local cache (see also `dvc fetch`).

Probably still doesn't explain why but at least it describes the scenario more clearly, I think.

Status for files inside DVC-tracked directories may be reported as "unknown" if information about directories is missing from the cache yet (see ...)

improve top admons in data status and dvc data status

jorgeorpinel

OK well I guess it's all approved now. The only change after that is improved cross-tip admon/links:

jorgeorpinel · 2022-10-18T07:26:11Z

content/docs/command-reference/data/status.md

+<admon type="tip">

-For [pipelines](/doc/user-guide/pipelines) status, use `dvc status`.
+For the status of <abbr>data pipelines</abbr>, see `dvc status`.

 </admon>


jorgeorpinel · 2022-10-18T07:26:20Z

content/docs/command-reference/status.md

+<admon type="tip">

-For an equivalent to `git status`, use `dvc data status`.
+For the status of tracked data, see `dvc data status` (similar to `git status`).


github-actions · 2022-10-18T07:37:11Z

f7a4e67

Link Check Report

There were no links to check!

ref: update data status intro

6b1a4ab

per #3812 (comment)

shcheklein temporarily deployed to dvc-org-ref-data-status-bnsygg September 6, 2022 20:16 Inactive

jorgeorpinel mentioned this pull request Sep 6, 2022

ref: data status #3812

Merged

jorgeorpinel added A: docs Area: user documentation (gatsby-theme-iterative) C: ref Content of /doc/*-reference labels Sep 6, 2022

ref: update data status explanations

d0aef73

per #3812 (comment)

shcheklein temporarily deployed to dvc-org-ref-data-status-bnsygg September 6, 2022 20:20 Inactive

jorgeorpinel commented Sep 6, 2022

View reviewed changes

ref: update data status --granular explanation

d5b1373

per #3812 (comment)

shcheklein temporarily deployed to dvc-org-ref-data-status-bnsygg September 6, 2022 20:23 Inactive

ref: remove redundant data status example

9105ff4

per #3812 (comment)

shcheklein had a problem deploying to dvc-org-ref-data-status-bnsygg September 6, 2022 20:23 Failure

jorgeorpinel marked this pull request as ready for review September 6, 2022 20:23

jorgeorpinel requested a review from dberenbaum September 6, 2022 20:25

shcheklein reviewed Sep 6, 2022

View reviewed changes

content/docs/command-reference/data/status.md Outdated Show resolved Hide resolved

shcheklein reviewed Sep 6, 2022

View reviewed changes

shcheklein requested changes Sep 6, 2022

View reviewed changes

jorgeorpinel commented Sep 6, 2022

View reviewed changes

content/docs/command-reference/data/status.md Outdated Show resolved Hide resolved

content/docs/command-reference/data/status.md Outdated Show resolved Hide resolved

ref: roll back data status prefixes

23c7eb8

restyled-io bot mentioned this pull request Sep 6, 2022

Restyle ref: data status updates #3925

Merged

Restyled by prettier (#3925)

d925744

Co-authored-by: Restyled.io <[email protected]>

shcheklein temporarily deployed to dvc-org-ref-data-status-bnsygg September 6, 2022 22:01 Inactive

shcheklein reviewed Sep 6, 2022

View reviewed changes

content/docs/command-reference/data/status.md Outdated Show resolved Hide resolved

shcheklein reviewed Sep 6, 2022

View reviewed changes

content/docs/command-reference/data/status.md Outdated Show resolved Hide resolved

jorgeorpinel added 3 commits September 7, 2022 01:05

Merge branch 'main' into ref/data-status

725c7e4

ref: reinstate duplicated example in data status

9ae9bd7

per #3924 (comment)

Merge branch 'ref/data-status' of github.com:iterative/dvc.org into r…

70f1cb0

…ef/data-status

shcheklein temporarily deployed to dvc-org-ref-data-status-bnsygg September 7, 2022 05:07 Inactive

shcheklein temporarily deployed to dvc-org-ref-data-status-bnsygg September 7, 2022 05:44 Inactive

shcheklein reviewed Sep 7, 2022

View reviewed changes

content/docs/command-reference/data/status.md Outdated Show resolved Hide resolved

ref: simplify term "tracked dirs"

1cf235b

per #3924 (review)

shcheklein temporarily deployed to dvc-org-ref-data-status-bnsygg September 7, 2022 06:04 Inactive

shcheklein approved these changes Sep 7, 2022

View reviewed changes

skshetry reviewed Sep 9, 2022

View reviewed changes

content/docs/command-reference/data/status.md Outdated Show resolved Hide resolved

skshetry reviewed Sep 9, 2022

View reviewed changes

content/docs/command-reference/data/status.md Outdated Show resolved Hide resolved

skshetry reviewed Sep 9, 2022

View reviewed changes

content/docs/command-reference/data/status.md Outdated Show resolved Hide resolved

skshetry reviewed Sep 9, 2022

View reviewed changes

Merge branch 'main' into ref/data-status

ce29566

shcheklein temporarily deployed to dvc-org-ref-data-status-bnsygg September 13, 2022 01:30 Inactive

ref: note unknown data status for --granular

aca9d8a

rel #3924 (review)

shcheklein temporarily deployed to dvc-org-ref-data-status-bnsygg September 13, 2022 01:37 Inactive

ref: avoid term "file records"

87c8f51

per #3924 (review)

shcheklein deployed to dvc-org-ref-data-status-bnsygg September 13, 2022 01:42 View deployment

ref: restore whitespaces

7e15f6e

shcheklein temporarily deployed to dvc-org-ref-data-status-bnsygg September 13, 2022 01:45 Inactive

jorgeorpinel requested review from dberenbaum and removed request for dberenbaum September 13, 2022 01:46

jorgeorpinel commented Sep 13, 2022

View reviewed changes

dberenbaum approved these changes Sep 14, 2022

View reviewed changes

This comment was marked as resolved.

Sign in to view

Merge branch 'main' into ref/data-status and

9c11972

improve top admons in data status and dvc data status

This comment was marked as resolved.

Sign in to view

jorgeorpinel added the p2-nice-to-have Less of a priority at the moment. We don't usually deal with this immediately. label Oct 18, 2022

jorgeorpinel commented Oct 18, 2022

View reviewed changes

jorgeorpinel merged commit f7a4e67 into main Oct 18, 2022

jorgeorpinel deleted the ref/data-status branch October 18, 2022 07:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ref: `data status` updates #3924

ref: `data status` updates #3924

jorgeorpinel commented Sep 6, 2022

jorgeorpinel Sep 6, 2022

dberenbaum Sep 8, 2022

jorgeorpinel Sep 13, 2022 •

edited

Loading

dberenbaum Sep 13, 2022

skshetry Sep 14, 2022

jorgeorpinel commented Sep 6, 2022 •

edited

Loading

github-actions bot commented Sep 6, 2022 •

edited

Loading

shcheklein Sep 6, 2022

jorgeorpinel Sep 6, 2022 •

edited

Loading

shcheklein Sep 6, 2022

jorgeorpinel Sep 7, 2022 •

edited

Loading

shcheklein left a comment

jorgeorpinel left a comment

skshetry Sep 9, 2022

skshetry Sep 9, 2022

jorgeorpinel Sep 13, 2022 •

edited

Loading

dberenbaum Sep 14, 2022

skshetry Sep 9, 2022

jorgeorpinel Sep 13, 2022

jorgeorpinel Sep 13, 2022 •

edited

Loading

jorgeorpinel Sep 13, 2022

shcheklein Sep 13, 2022

jorgeorpinel Sep 13, 2022 •

edited

Loading

shcheklein Sep 13, 2022

This comment was marked as resolved.

This comment was marked as resolved.

jorgeorpinel left a comment

jorgeorpinel Oct 18, 2022

jorgeorpinel Oct 18, 2022

github-actions bot commented Oct 18, 2022

		@@ -83,31 +88,6 @@ option.

		- `-v`, `--verbose` - displays detailed tracing information.

		## Examples

	- _DVC committed changes_ are new, modified, or deleted tracked files or
	- _DVC committed changes_ are added, modified, or deleted tracked files or

ref: data status updates #3924

ref: data status updates #3924

Conversation

jorgeorpinel commented Sep 6, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jorgeorpinel Sep 13, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jorgeorpinel commented Sep 6, 2022 • edited Loading

github-actions bot commented Sep 6, 2022 • edited Loading

Link Check Report

Choose a reason for hiding this comment

jorgeorpinel Sep 6, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jorgeorpinel Sep 7, 2022 • edited Loading

Choose a reason for hiding this comment

shcheklein left a comment

Choose a reason for hiding this comment

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

jorgeorpinel Sep 13, 2022 • edited Loading

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

jorgeorpinel Sep 13, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jorgeorpinel Sep 13, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

This comment was marked as resolved.

This comment was marked as resolved.

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

github-actions bot commented Oct 18, 2022

Link Check Report

ref: `data status` updates #3924

ref: `data status` updates #3924

jorgeorpinel Sep 13, 2022 •

edited

Loading

jorgeorpinel commented Sep 6, 2022 •

edited

Loading

github-actions bot commented Sep 6, 2022 •

edited

Loading

jorgeorpinel Sep 6, 2022 •

edited

Loading

jorgeorpinel Sep 7, 2022 •

edited

Loading

jorgeorpinel Sep 13, 2022 •

edited

Loading

jorgeorpinel Sep 13, 2022 •

edited

Loading

jorgeorpinel Sep 13, 2022 •

edited

Loading