coreutils: Target directory

1 
1 2.8 Target directory
1 ====================
1 
1 The ‘cp’, ‘install’, ‘ln’, and ‘mv’ commands normally treat the last
1 operand specially when it is a directory or a symbolic link to a
1 directory.  For example, ‘cp source dest’ is equivalent to ‘cp source
1 dest/source’ if ‘dest’ is a directory.  Sometimes this behavior is not
1 exactly what is wanted, so these commands support the following options
1 to allow more fine-grained control:
1 
1 ‘-T’
1 ‘--no-target-directory’
1      Do not treat the last operand specially when it is a directory or a
1      symbolic link to a directory.  This can help avoid race conditions
1      in programs that operate in a shared area.  For example, when the
1      command ‘mv /tmp/source /tmp/dest’ succeeds, there is no guarantee
1      that ‘/tmp/source’ was renamed to ‘/tmp/dest’: it could have been
1      renamed to ‘/tmp/dest/source’ instead, if some other process
1      created ‘/tmp/dest’ as a directory.  However, if ‘mv -T /tmp/source
1      /tmp/dest’ succeeds, there is no question that ‘/tmp/source’ was
1      renamed to ‘/tmp/dest’.
1 
1      In the opposite situation, where you want the last operand to be
1      treated as a directory and want a diagnostic otherwise, you can use
1      the ‘--target-directory’ (‘-t’) option.
1 
1 ‘-t DIRECTORY’
1 ‘--target-directory=DIRECTORY’
1      Use DIRECTORY as the directory component of each destination file
1      name.
1 
1      The interface for most programs is that after processing options
1      and a finite (possibly zero) number of fixed-position arguments,
1      the remaining argument list is either expected to be empty, or is a
1      list of items (usually files) that will all be handled identically.
1      The ‘xargs’ program is designed to work well with this convention.
1 
1      The commands in the ‘mv’-family are unusual in that they take a
1      variable number of arguments with a special case at the _end_
1      (namely, the target directory).  This makes it nontrivial to
1      perform some operations, e.g., “move all files from here to ../d/”,
1      because ‘mv * ../d/’ might exhaust the argument space, and ‘ls |
1      xargs ...’ doesn’t have a clean way to specify an extra final
1      argument for each invocation of the subject command.  (It can be
1      done by going through a shell command, but that requires more human
1      labor and brain power than it should.)
1 
1      The ‘--target-directory’ (‘-t’) option allows the ‘cp’, ‘install’,
1      ‘ln’, and ‘mv’ programs to be used conveniently with ‘xargs’.  For
1      example, you can move the files from the current directory to a
1      sibling directory, ‘d’ like this:
1 
1           ls | xargs mv -t ../d --
1 
1      However, this doesn’t move files whose names begin with ‘.’.  If
1      you use the GNU ‘find’ program, you can move those files too, with
1      this command:
1 
1           find . -mindepth 1 -maxdepth 1 \
1             | xargs mv -t ../d
1 
1      But both of the above approaches fail if there are no files in the
1      current directory, or if any file has a name containing a blank or
1      some other special characters.  The following example removes those
1      limitations and requires both GNU ‘find’ and GNU ‘xargs’:
1 
1           find . -mindepth 1 -maxdepth 1 -print0 \
1             | xargs --null --no-run-if-empty \
1                 mv -t ../d
1 
1 The ‘--target-directory’ (‘-t’) and ‘--no-target-directory’ (‘-T’)
1 options cannot be combined.
1