status: what should be the default behavior and distinction to diff?

[dmpetrov]

git status and git diff have different syntax (diff is based on checksums, status - not) and semantics (diff is based on history, status - on workspace and index).

dvc diff and dvc status have different syntax with similar semantics because dvc diff is not doing an actual content diff. So, these commands could be potentially "merged" into a single one.

Even if we decide to keep both I'd still prefer to see a status-like output for dvc diff when a file was not added to the repo by dvc add.

[jorgeorpinel]

There's definitely perceived overlap, which may be confusing to new users accustomed to git status and git diff which don't really have such an overlap.

I played with both commands and came up with this comparative summary:

• dvc status always works for all projects (even non-Git). It always compares DVC-file data vs. actual files in the workspace, and reports this info grouped by DVC-file.
  Main use: Know when to run dvc add or dvc repro, and on which targets.
• The new dvc diff only works for Git+DVC repos. It should compare HEAD vs local changes by default I think (similar to dvc status) but you can pick any 2 Git refs A..B (as long as A comes before B). Reports found differences in added/deleted/modified groups + count summary.
  Main use: Compare DVC repo versions

So clearly their motivations and purposes are different right now. But still, they are somewhat confusing given possible overlap and similar output. My suggestion would be to keep both but consider redesigning dvc diff (at some point).

I think dvc status is OK because the Git analogy is pretty good.

Conclusion

dvc diff is the tricky one: on the one hand we have the confusion explained above; on the other, it takes the same 2 arguments as dvc diff (2 commits) AND it has the same purpose (compare repo/object versions) so the Git analogy is also good. For this reason I don't see a strong argument to change it soon.

Perhaps reordering the output of dvc diff by data file instead of by type of change would make it feel less like a "status" report, but we just redesigned the output in #3229...

I think the real solution will be when/if #770 is addressed (some sort of semantic data format plugins).

[dmpetrov]

I don't see a strong argument to change it soon.

Agree.

I think the real solution will be when/if #770 is addressed (some sort of semantic data format plugins).

💯 Both will be needed with content diff

[ghost]

Related: #1406

[jorgeorpinel]

Another distinction between status and diff is that the former checks untracked workspace changes (same as Git working tree) while the latter checks tracked but uncommitted changes in the workspace (including Git staged DVC-file and .gitignore for ex.) So that's another reason to close this one, I think?

We're working on just improving the docs to clarify all this. See iterative/dvc.org#953 (review).

[shcheklein]

Another distinction between status and diff is that the former checks untracked workspace changes (same as Git working tree) while the latter checks tracked but uncommitted changes in the workspace (including Git staged DVC-file and .gitignore for ex.)

I don't quite understand this. But if my intuition is correct that this hasn't been decided yet.

My 2c regarding status vs diff. They are different from a different perspective (as just committed/uncommitted stuff).

• diff compares things (data in this case). The evolution of diff can go into showing more details
  about how files/experiments are different.
• status purpose to show you the current state of the workspace. It might potentially include some diff information (diff in its default sense) with a different UI/UX (e.g. sliced by pipeline stages) but that's fine. I think in the long term there can be way more to this. And even now if we take a closer look - status is showing that status of the pipeline (to see if you need to run repro, on what stages, etc), while diff is comparing data states.

[jorgeorpinel]

I don't quite understand this

Yeah it's confusing. I think your approach of looking at is from the PoV of DVC outputs + dependencies (#3385) is easier to understand. But from an implementation standpoint, it's also worth mentioning the difference between Git-unstaged changes (not yet tracked by DVC) vs. staged changes (uncommitted, but already tracked by DVC): which should be shown by status, and which by diff (#3385, #3386).

if my intuition is correct that this hasn't been decided yet

OK so due to ^ and also per #3386 (comment), this issue will be mostly to decide what the behavior of dvc status should be and whether it's already doing it or needs changes.

[shcheklein]

Git-unstaged changes (not yet tracked by DVC)

I don't understand the meaning of this, sorry :( At least, I'm not 100% sure that we are on the same page here.

staged changes (uncommitted, but already tracked by DVC)

same here

May be we can start w/o using some specific examples?

[jorgeorpinel]

OK, dvc add-based example:

0. Init DVC repo.

$ mkdir test-dvc-diff
$ cd test-dvc-diff
$ git init
$ dvc init
$ git commit -m 'dvc init'

Note: At this point ^ dvc diff throws an error. See #3398

1. New data

# 1.0
$ echo foo > data  # create data file (not yet tracked)
$ git status         # -> sees new data as *unstaged*
$ git diff           # doesn't see anything yet
$ dvc status         # doesn't see anything yet 
$ dvc diff           # doesn't see anything yet

# 1.1
$ dvc add data     # track data file with DVC
$ git status         # -> sees new data.dvc as *unstaged*
# git diff and dvc status don't see anything yet
$ dvc diff           # -> sees new data (tracked by DVC but uncommitted)
Added:                                                                  
    data

files summary: 1 added, 0 deleted, 0 modified

# 1.2
$ git add --all    # track new data.dvc with Git
$ git status         # -> sees data.dvc as *staged*
# git diff and dvc status don't see anything yet
$ dvc diff           # -> sees data (tracked by DVC but uncommitted)

# 1.3
$ git commit -m 'echo foo > data'  # commit data version to Git
# blank slate: all status and diff commands see nothing

Summary: only dvc diff cares about new data.

2. Changes in data

# 2.0
$ echo bar > data  # change data
# git status and git diff see nothing
$ dvc status         # -> sees change in tracked data
data.dvc:                                                               
	changed outs:
		modified:           data
$ dvc diff           # doesn't see the change

# 2.1
$ dvc add data     # update the tracked data with DVC
$ git status         # -> sees data.dvc as *unstaged*
$ git diff           # -> displays diff in data.dvc from HEAD to working tree
$ dvc status         # Up to date again. 
$ dvc diff           # -> sees data change (tracked by DVC but uncommitted)
Modified:                                                               
    data

files summary: 0 added, 0 deleted, 1 modified

# 2.2
$ git add --all    # track change in data.dvc with Git
$ git status         # -> sees data.dvc as a staged file
# git diff and dvc status don't care
$ dvc diff           # -> still sees data change (tracked by DVC but uncommitted)

# 2.3
$ git commit -m 'echo bar > data'  # blank slate again

(Repeat.)
Summary: dvc status tells you when tracked data has changed (invisible to dvc diff). dvc diff compares DVC-tracked changes (uncommitted, whether staged or not) vs. HEAD.

[shcheklein]

... dvc diff compares Git-staged changes vs. HEAD

it's not exactly right I think, right? dvc diff can see changes even in unstaged files, I'm not sure it cares even if they are tracked with Git at the moment at all - I would check that. Unless I'm missing something.

Summary: dvc status tells you when tracked data has changed

That's what I would expect from dvc diff, that how git diff behave. And again, I don't think we need to change anything about dvc status - it's a separate discussion. They might overlap and it's fine - they just have different purposes to solve different use cases.

[jorgeorpinel]

dvc diff compares Git-staged changes vs. HEAD

it's not exactly right I think, right?

🤦‍♂ sorry I meant "DVC-tracked changes (whether Git staged or not)"! (Original comment updated.)

I'm not sure it cares even if they are tracked with Git at the moment

Depends what you mean by "tracked":

• Unstaged vs. staged? dvc diff doesn't care.
• (Un)staged vs. committed? It makes a difference for dvc diff without arguments.

[shcheklein]

sorry I meant "DVC-tracked changes

this is confusing or not true either. To my mind if I add a file into a dir and this dir is DVC-tracked I suppose to see the difference, right? But this does not happen. (like git diff actually always show you difference in the Git-tracked files).

Depends what you mean by "tracked".

I mean that it just reads DVC-files from the working tree, it does not probably analyze anything related to Git about them.

[jorgeorpinel]

Summary: dvc status tells you when tracked data has changed

That's what I would expect from dvc diff, that how git diff behave. And again, I don't think we need to change anything about dvc status - it's a separate discussion.

I think I agree with you about dvc diff @shcheklein, but actually I think that's the "separate discussion" (maybe #3385 or #3386). This issue is about dvc status officially, I think. But it doesn't matter too much... as long as we can come to some solutions.

So is the main take away so far that dvc status/diff should both have an output under the same conditions as git status/diff do? (As you can see from the steps above, that's not the case currently.)

not true either. To my mind if I add a file into a dir and this dir is DVC-tracked I suppose to see the difference, right?

@shcheklein Not if you haven't run dvc add <dir> to update the DVC-tacked dir yet. See step 2.0 above.

[efiop]

@shcheklein To me it feels like you could ask the same question about git status and git diff. And for git it is obvious that they are not the same, right? It feels similar here with dvc status and dvc diff, they are not the same.

[shcheklein]

To me it feels like you could ask the same question about git status and git diff

what question?

they are not the same.

@efiop yep, I think I was not arguing about this - #3255 (comment) ... at least may be I was not clear enough? or missed something?

[efiop]

For the record: had a discussion during the call about it, looks like I mistook it for "throw out diff because it is the same as status", which is now resolved.