cmd: update commit-related info.

[jorgeorpinel]

Extracted from #1978 (comment)

• Includes some misc. updates carried from Misc. updates #1978
• Happens to fix cmd ref: add a few lines about cache and no-commit in dvc run #186

Also rel. iterative/dvc/issues/5000

Note for self:

• Finalize the commit part of cmd: help output updates (per docs) dvc#4999 when this is done.

[jorgeorpinel]

PTAL @shcheklein

[shcheklein]

Not sure Other applies here? it's more like a detailed explanation?

[jorgeorpinel]

Hmmm they're meant as different scenarios. The part before this is about add/run/repro --no-commit + dvc commit — main use case. The bullets in this list are

• dvc add *
• force-accepting cosmetic changes to dependencies
• adding missing deps/outs
• executing commands manually (this one I guess is pretty similar to the main case)

[shcheklein]

some of them (all of them?) are part of the main use case in this terminology.

add/run/repro --no-commit is not even a use case by itself, right? it doesn't explain a specific need.

[jorgeorpinel]

I thought the main reason commit exists as a stand-alone command is to complement the --no-commit options of add/run/repro?

In terms of the "story", its explained as "forces DVC to accept the contents of tracked data currently in the workspace" in the first p of the description. So do you mean they're all different flavors of that explanation and that there should be a single bullet list (including add/run/repro --no-commit)?

[shcheklein]

I thought the main reason commit exists as a stand-alone command is to complement the --no-commit options of add/run/repro?

probably initially it was the case, now we reference it in other places? (like --no-exec?) So we might need to revisit, generalize? (not 100% sure, just asking)

So do you mean they're all different flavors of that explanation

it seems so (not sure about all)

that there should be a single bullet list

ah, not necessarily. Just removing Other might help? or rephrasing it a bit if the first paragraph is already general.

again, not very constructive feedback here - just highlighting stuff as I read it, a think that seemed strange

[jorgeorpinel]

Gotcha. I iterated on this to make clear that the first p is a generalization, then a main scenario is explained, and finally a list with other scenarios. PTAL.

[shcheklein]

Overall it's great, just a few minor comments to iterate on

[shcheklein]

you have repetition useful ... useful

[jorgeorpinel]

Hm yeah this sentence wasn't great, sorry... Updated in d3ed553.

[shcheklein]

it's repetitive with the last sentence of the previous paragraph, essentially it reads:

something. It is useful when A.

This is useful when B.

is it intentional?

and overall it got complicated again. Is there a way to merge A and B?

[jorgeorpinel]

True. I guess this is why we didn't have so much motivation in the --no-exec options before... I tried to merge it now but it's still a little long.

Maybe we should remove the part about "if the file/directory already exists locally"? It seems like a very edge case to download something manually and THEN register it with import.

[jorgeorpinel]

Maybe we should remove the part about "if the file/directory already exists locally"

Yeah, I removed that to simplify.

[jorgeorpinel]

I suggest we don't obsess over the --no-exec text for now and instead open/reactivate core tickets to make that the default behavior, at least for run (which would need to be renamed probably) — since it's supposed to be a helper for writing dvc.yaml files.

It's also an interesting question what to do with the import commands. I think that .dvc files could be phased and all tracked data could be included in a section of dvc.yaml (before stages, see iterative/dvc#3936 (comment)) so in that case --no-exec should also be the default behavior.