Tldr: cp: redundant recursive copy examples

[arunisaac]

The third and fourth examples in the cp tldr page are the same. They should not be repeated as though they were two different commands.

[sbrl]

Hey, good spot - thanks @arunisaac! Would you like to send a pull request?

[agnivade]

I dont think that is a mistake. @waldyrious wrote that page. See that examples 2 and 4 are of the same variant.

But I do see that functionally there is no difference. @waldyrious ?

[arunisaac]

Examples 1 and 2 are functionally different. They do different things. But examples 3 and 4 are the exact same command. This would be confusing to the reader, and therefore, I think this is a bug.

[waldyrious]

@arunisaac, @agnivade, @sbrl -- sorry for the much delayed response. I'm trying to go through my backlog little by little :)

If I recall correctly from #964, the reason for those two examples was that if the target path already exists, the original folder is copied into it, keeping its original name; while if the target path does not exist, the copied folder takes the name of the last portion of the target path (assuming the path up to there exists), and its contents are copied there.

This demonstration might make things clearer:

$ cd /tmp
$ mkdir original
$ touch original/test.txt
$ ls original
test.txt
$ cp -r original target
# The "target/" folder did not exist, and was created by the command above
$ ls target
test.txt
$ cp -r original target
# This time, "target/" already existed, so "original/" is copied into it
$ ls target
original  test.txt

I acknowledge that the descriptions and token names we ended up picking back then may not have made this clear, but I think it's an important behavior of cp that we ought to document in its tldr page, since it pertains to such a basic operation.

Would something like this make the behavior clearer?

- Copy a folder's contents recursively to a new location:

`cp -r {{path/to/folder}} {{path/to/new/folder/name}}`

- Copy a folder and its contents recursively into another folder:

`cp -r {{path/to/folder}} {{path/to/existing/folder}}`

(I'm reopening this issue since #2486 may need to be reverted.)

[agnivade]

I think people are focusing more on the example rather than the description. Here, both examples are the same cp -r source destination.

I think it might be better if we just amend the current description, since we already have a line on copying the contents of a folder into another folder.

- Copy a folder recursively to another location (if the location exists, only the folder's contents are copied):
    cp -r path/to/folder path/to/copy

[waldyrious]

I'd argue that the result is significantly different:

• the folder name in the copy changes in one case, but doesn't in the other;
• the location of the copy ends up at different levels of the filesystem hierarchy in both cases
• as you say yourself, the current example can be thought of as copying the _contents_ of a folder to a different location, while the other is about copying the entire folder plus its contents.

That said, I understand that the actual command syntax is the same, and if you insist, I can live with the description being improved rather than restoring the second example. I'm just not sure we can explain the subtlety in a manner that's both concise and sufficiently clear. Heck, even my previous two examples failed to convey the difference well enough! (And by the way, your note in parenthesis is the opposite of what actually happens 😄)

The root of the issue is the age-old problem (and one very relevant to the tldr-pages project) that it's easy for a concise description to make sense if you already have the correct mental model, but the challenge is being able to convey the model from scratch to someone who isn't aware of it in a short sentence...

[agnivade]

And by the way, your note in parenthesis is the opposite of what actually happens

Oops ! sorry.

Yes, it is indeed challenging to convey the model from scratch. Can you give a shot in improving the existing example further ? I would like to see how it looks like (since mine was wrong anyways :P) before going for a 2 example solution.

[waldyrious]

Sure. I'll mull this over tonight™ and will make a proposal.

[waldyrious]

The best I can muster is something like this:

- Recursively copy a folder's contents to a new location (if the destination exists, the folder is copied inside it):
`cp -r {{path/to/original-folder}} {{path/to/copy-folder}}`

...but I think it's too long, and I fear it may still not be not sufficiently clear :(

[agnivade]

Doesn't seem too long. We've had examples like these. @arunisaac / @sbrl - Does this look okay ?

[waldyrious]

Btw, while discussing this with my coworkers, I was reminded that this behavior also happens with mv. I don't want to tackle reworking that page too, though (for the time being at least). Just leaving the note for future reference.

[agnivade]

ping @sbrl / @pxgamer for comments.

[owenvoke]

I hadn't seen this issue until now (oops).

I think that updated description seems fine (and I have seen some which are quite a bit longer). It's difficult to get some functionality across in short messages. I do however understand it being split into 2, due to the differences between them (even though the usage examples are identical) and I would hope people would see the descriptions are different. However, as we are going with a single example with an updated description for now I think this seems fine. :+1:

[sbrl]

That suggestion looks good, @waldyrious - it might be better if we can consolidate into fewer examples in this case, as it feels slightly more obvious.

[arunisaac]

I agree with @waldyrious last suggestion. It is a good idea to have a
single example with a more complicated description that explains the
different effects caused by the existence or lack thereof of the
destination folder. Having two examples with the same command but
different descriptions will only serve to confuse the reader.

[agnivade]

@waldyrious - Do you have something more on this, or we can go ahead with the last example ?