plots: diff: targets and revisions behaviour

[pared]

When --targets is present, argument parser will not be able to grab revisions, due to fact that both options use nargs='*'.

[efiop]

How about --revs then? CC @dmpetrov @Suor

[dmpetrov]

It should work the same way with the same params as metrics diff. Do we have the same issue with ht metrics command?

[pared]

@dmpetrov

It should work the same way with the same params as metrics diff

I think we should discuss it. Arg parser allows us to have only one multiple-params argument (or few optional). So I guess it all boils down to question whether API consistency and ability to diff multiple targets is more desired than being able to plot multiple revisions on a single plot. In initial discussions, I got the impression that we need to support multiple revisions. I would consider treating plots differently, because they are a bit different than metrics. It's hard to diff (eg) 10 metrics revision in a comprehensive matter. In case of plot (especially default one), it is easy to do that - you only get 10 lines on a single plot, which visually is easy to understand.

[efiop]

@pared @dmpetrov Btw, it mixes them up only if you do that explicitly:

dvc plots diff --targets t1 t2 r1 r2 r3 r4

but it is actually normal, there is a special -- that argparse (and, well, most of CLI tools, e.g. git) supports natively when you need to tell it that you are done declaring the args for one of the options:

dvc plots diff --targets t1 t2 -- r1 r2 r3 r4

and normal stuff like

dvc plots diff r1 r2 r3 r4 --targets t1 t2

works fine.

Same with metrics diff. So we don't really need to do anything, unless we really want to make this explicit too.

[dmpetrov]

Agree with @efiop - we can keep it as-is and just remember this trick. I still feel like it can confuse some users and we should be prepared for this. But it looks like the best solution for today.

Let's keep as-is and close this issue! What do you think @pared?

[pared]

@dmpetrov @efiop I agree, lets close it. I will create ticket for docs for that issue. I think some kind of a Note under dvc plots diff section of documentation could save some hassle. And regretfully, it's not easy to find the -- usage instructions in python docs. I was not aware of that.

[Suor]

Show we add examples to our dvc <command> --help?