From ff6fe3d17d9294f2494b4535a320bc9bfc86cc49 Mon Sep 17 00:00:00 2001
From: Jim Meyering <meyering@redhat.com>
Date: Mon, 15 Jun 2009 09:10:50 +0200
Subject: doc: cp: describe an oddity of combining -H/-L and --preserve=links

* doc/coreutils.texi (cp invocation) [-L]: Elaborate.
[--preserve=links]: Remove comments saying that we need documentation
for just this situation.  Provide more explanation and examples.
Reported by Brian M. Carlson in http://bugs.debian.org/525048.
---
 doc/coreutils.texi | 26 ++++++++++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

(limited to 'doc')

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 155858b54..180629520 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -7388,6 +7388,9 @@ Make hard links instead of copies of non-directories.
 @opindex -L
 @opindex --dereference
 Follow symbolic links when copying from them.
+With this option, @command{cp} cannot create a symbolic link.
+For example, a symlink (to regular file) in the source tree will be copied to
+a regular file in the destination tree.
 
 @item -n
 @itemx --no-clobber
@@ -7435,8 +7438,27 @@ not yet take advantage of that.
 @itemx links
 Preserve in the destination files
 any links between corresponding source files.
-@c Give examples illustrating how hard links are preserved.
-@c Also, show how soft links map to hard links with -L and -H.
+Note that with @option{-L} or @option{-H}, this option can convert
+symbolic links to hard links.  For example,
+@example
+$ mkdir c; : > a; ln -s a b; cp -aH a b c; ls -i1 c
+74161745 a
+74161745 b
+@end example
+@noindent
+Note the inputs: @file{b} is a symlink to regular file @file{a},
+yet the files in destination directory, @file{c/}, are hard-linked.
+Since @option{-a} implies @option{--preserve=links}, and since @option{-H}
+tells @command{cp} to dereference command line arguments, it sees two files
+with the same inode number, and preserves the perceived hard link.
+
+Here is a similar example that exercises @command{cp}'s @option{-L} option:
+@smallexample
+$ mkdir b c; (cd b; : > a; ln -s a b); cp -aL b c; ls -i1 c/b
+74163295 a
+74163295 b
+@end smallexample
+
 @itemx context
 Preserve SELinux security context of the file. @command{cp} will fail
 if the preserving of SELinux security context is not succesful.
-- 
cgit v1.2.3-70-g09d2