bug#20849: documentation: difference between empty and non-empty dirs with "mv --no-target-directory"

[Alexey Salmin]

Image you need to move the "$PWD/tmploc/a" directory into "$PWD/a" and
ensure you don't end up with "$PWD/a/a" when "$PWD/a" already exists.
The "mv --no-target-directory" (or "mv -T") does exactly that, however
there are three different cases depending on a type of "$PWD/a":

A) Empty directory: mv silently overwrites "$PWD/a" with "$PWD/tmploc/a"
B) Non-empty directory: mv fails with a "File exists" message
C) File: mv fails with a "cannot overwrite non-directory ... with
directory" message
See steps to reproduce at the bottom of this e-mail.

I can see a reasoning behind this behavior and don't challenge it.
However I would appreciate if it was clearly stated in the
documentation.

At the moment it explains "-T" as "Do not treat the last operand
specially when it is a directory or a symbolic link to a directory."
[1] This sort of contradicts the fact that an empty directory (A) is
treated specially compared to an empty file (C). And a difference
between (A) and (B) is not mentioned at all.

Thank you,
Alexey


[1] http://www.gnu.org/software/coreutils/manual/coreutils.html#mv-invocation

Steps to reproduce:
A) Empty directory: mv silently overwrites "$PWD/a" with "$PWD/tmploc/a"
$ find * -printf "%y %p\n"
d a
f a/otherfile
d tmploc
d tmploc/a
f tmploc/a/file
$ mv --no-target-directory tmploc/a a; echo $?
mv: cannot move 'tmploc/a' to 'a': File exists
1

B) Non-empty directory: mv fails with a "File exists" message
$ rm a/otherfile
$ mv --no-target-directory tmploc/a a; echo $?
0
$ find * -printf "%y %p\n"
d a
f a/file
d tmploc

C) File: mv fails with a "cannot overwrite non-directory ... with
directory" message
$ find * -printf "%y %p\n"
f a
d tmploc
d tmploc/a
f tmploc/a/file
$ mv --no-target-directory tmploc/a a; echo $?
mv: cannot overwrite non-directory 'a' with directory 'tmploc/a'
1