cmd ref: add checkout --relink option, improve checkout desc.

[Suor]

No description provided.

[shcheklein]

a minor comment

I wonder if it would be valuable to add a sentence or two into the description that clarifies the semantics (that we don't relink by default and it's user's responsibility)

[Suor]

Higher on same page: "For any data files where the checksum doesn't match their DVC-file entry, the
data file is restored from the cache. The link strategy ..."

So --relink description builds on top of that: "recreates links ... even ones with unchanged checksums"

[Suor]

Reordered it everywhere to be from common to rare options: -d, -R, -f, --relink.

Related: iterative/dvc#2966

[jorgeorpinel]

Guys, I took over this PR, sorry. I just had to basically rewrite much of the description to make things clearer. Thanks @Suor for explaining your points in #864 (review), marked resolved now. But please review the changes here and lmk or feel free to make further changes for us to make a final review. Thanks!

[Suor]

recreates (overwrites) links or copies from cache to workspace
for all outputs in the workspace, including the ones normally
checked out by this command, as well as existing ones with matching
checksums in current DVC-files.

"including the ones normally
checked out by this command" makes this really hard to get, "this command does what it normally does, including something ...". And you are making bold "existing", which is not the point, dvc checkout without relink also overwrites existing files.

[jorgeorpinel]

Just pending to figure out #864 (review) ^

[shcheklein]

thanks @jorgeorpinel @Suor !