Update the cmd entry of the dvc.yaml file to add cmd as list option

[ClementWalter]

Update the dvc.yaml documentation with the list possibility for the cmd entry.

Core PR #4934

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

[jorgeorpinel]

Fix #4373

I don't think this docs PR fixes a core issue 🙂 please link to the core PR this matches instead (don't link them). Thanks

[jorgeorpinel]

Left a suggestion ^ Also:

• The dvc.yaml example should show multiple commands, probably. Any other dvc.yaml examples throughout docs that could feature this?
• And what about the cmd refs? At least https://dvc.org/doc/command-reference/run needs an update, I think. Maybe repro

Thanks

[jorgeorpinel]

Oh and BTW the PR checks are failing, please follow https://dvc.org/doc/user-guide/contributing/docs (we can also merge the restyled PR #1981 if needed but preferably, it shouldn't be necessary).

[ClementWalter]

• And what about the cmd refs? At least https://dvc.org/doc/command-reference/run needs an update, I think. Maybe repro

Do you think that the dvc run should handle a command, with, for instance, && so as to make it eventually a list in the dvc.yaml? I may be nice, but I am not sure it is the desired behavior because it requires some parsing of the user command, which, indeed, does not seem to be a preferred choice. @efiop, an idea about that?

[efiop]

@ClementWalter I agree, that is not a desired behavior. List of commands could be only specified by hand by editing dvcfile, dvc run doesn't need to support it.

[jorgeorpinel]

dvc run doesn't need to support it.

Sounds good. But at the very least this will need checking the usage of the term "command" in repro (e.g. see -q option) and maybe other refs so it goes from singular to plural. Also it seems like the output of dvc repro will change slightly? There are a few examples that it would be ideal to update per this. Thanks

[ClementWalter]

@jorgeorpinel I try to rephrase, hopefully it is clearer. I have added a use case for a list of commands, hopefully relevant as well. What do you think?

[jorgeorpinel]

This is the actual output? Including a $ character?

[ClementWalter]

yes, it has changed from the previous "with command: \t {command}" to this with line beginning with $

[jorgeorpinel]

So repro becomes some sort of background process that actually enters commands into the user's shell? Or we specifically print the $ character + command string?

[ClementWalter]

we print it. Indeed it went from previous repeated "running command", to "> {command}" suggested by @skshetry to "$ {command}" because the ">" were confusing with possible ">" inside a command (like echo > file)

[shcheklein]

@ClementWalter @skshetry @efiop this can create a mess across all docs where we use $ as a starting symbol for all shell commands. We'll need some mechanism to escape it, and even if we do we'll end up with confusing text anyway - mix of actual commands and outputs. Let's reconsider this please. Also out of curiosity how exactly is it related to the PR (multiple commands), I mean this particular change in UI/UX? what was the reason to change it?

[skshetry]

Implemented this on treeverse/dvc#5041.

not sure > is great since it can be part of the command

For now, we add > instead of $. Let's discuss this on a different issue.

[skshetry]

Let's discuss this on a different issue.

Created treeverse/dvc#5043 to discuss this further.

[jorgeorpinel]

For now, we add > instead of $.

Actually right now it's a tab, why change it if we're not sure? I'd vote to roll back that change and yes to the discussion.

[jorgeorpinel]

Actually I'm back to having an opinion 😆 — see treeverse/dvc#5043 (comment)

[jorgeorpinel]

Thanks for all the details! Let's try to summarize this last bit about the cmd field though. And no worries, I can finish the writing at some point but I do have some questions about it before I can do that. My suggestions for now:

[jorgeorpinel]

I wonder if we need an example with multiple commands in repro...

[jorgeorpinel]

Moved to #2045

[skshetry]

Rest looks good, just one issue with the output format.

[ClementWalter]

I am not sure about the remaining changes to be brought to this PR.

[jorgeorpinel]

Hey no worries @ClementWalter I've assigned myself to finish up this one. Thanks!

[jorgeorpinel]

OK I removed "with command" from this file (for now, see treeverse/dvc#5043 (comment)) but there's another 4 instances/files with this text in the repo.

[jorgeorpinel]

I think this is mergeable pending #1980 (review) and #1980 (review) above, for a follow-up PR.

[shcheklein]

Thanks @ClementWalter , @jorgeorpinel , and @skshetry !

[jorgeorpinel]

Looks like this is a 2.0 feature so I removed it from the v1 branch in 365b768.