CLONE(1)

NAME
clone - make a clone of an entire directory tree

SYNOPSIS
clone [ -q ] [ -v ] [ -f ] [ -c | -s ] [ -S ] dir1 dir2

DESCRIPTION
Clone makes an identical copy of an entire (source) directory tree rooted at the directory named dir1 into the (target) directory tree rooted at dir2. The target directory dir2 will be created if it does not already exist. On the other hand, if the directory dir2 exists, or if the dir2 directory has any existing subdirectories, then these directories will not be deleted or replaced by clone.

Clone normally creates the clone directory tree by creating any new directories needed beneath dir2 (possibly including dir2 itself). Clone then fills in the new directories with hard links to all of the files in the original (source) directory tree dir1 such that the new (target) directory tree appears to also contain all of the files and subdirectories contained in the original (source) directory tree. Hard links are normally used when creating clones of the files in the source directory tree inside the new (target) directory tree. This insures that the cost (in disk space) of cloning a given source directory tree will be very low. If desired, the new (clone) directory tree can be filled in with symbolic links or with actual copies of the original files (instead of using hard links).

Clone may be particularly useful for maintaining multiple versions of nearly identical source trees.

An important feature of clone is that the dir2 argument may already exist and may already contain some files and subdirectories. In such cases, clone does not disturb these existing files or subdirectories. Rather, it simply adds the material from the source directory, dir1, to the material already present within dir2. In cases where there are conflicts between files or directories which already exist in dir2 but which also exist in dir1, clone (by default) leaves the files or directories in the target directory dir2 untouched unless the -f (force) flag is used, in which case, clone will override (i.e. delete) the conflicting entries from the target directory dir2 and replace them with clones from the source directory dir1.

OPTIONS
Clone recognizes the following options:

-q  Quite mode. Suppress all warnings and non-fatal error messages.

-v  Verbose mode. Print verbose messages which describe each individual linking (or copying) action, as well as all mkdir actions that clone executes.

-f  Force mode. In cases where an item (i.e. either a file or a directory) exists in the source directory tree dir1, and also already exists in the target directory tree dir2, delete the item (ether a file or a directory) in the target directory tree and then replace it with a clone of the corresponding item from the source directory tree. All such deletions causes warning to be issued to stderr unless the -q (quite mode) option is also specified. Note that if a given item already exists in the target directory tree, and if it also exists in the source directory tree, and if both the (existing) source and target items are themselves directories, then the -f option has no effect for these items. Existing directories in the target directory tree are never deleted by clone unless there is a corresponding item in the source directory tree which is not a directory (i.e. is a regular file) and the -f option is in effect.

-s  Symbolic link mode (not available on System V). When used, this option causes all non-directory files to be cloned by making symbolic links from the target directory tree into the source directory tree. This mode overrides the default mode in which hard links are used to clone all non-directory files.

-c  Copy mode. In this mode, a physical copy of each non-directory file in the source directory tree is created in the target directory tree. Note that when this mode is used, it is an error for the source directory tree to contain any block or character device files, or any named pipe files.

-S  SCCS mode. In this mode, only the source tree structure is cloned, not its contents. Symbolic links are created within the destination tree to subdirectories in the source tree named SCCS. This mode is useful when multiple developers work from a common SCCS project tree. To accomplish this, each developer creates a local project tree by cloning the common SCCS project directory, specifying the -S option. Individual developers are then able to work within their local project tree while ensuring that all SCCS operations are applied to the common SCCS project tree. Use of the -S option implies the use of the -s option and is thus not available on System V.

EXAMPLES
Assume that you have two directory trees called src1 and src2 and that you wish to combine the contents of these two directories into a new directory named dst such that if there are any files with duplicate names in both src1 and in src2 the files from the src2 directory tree will take precedence over the corresponding files in the directory tree src1. The following commands would accomplish this task:

clone src1 dst
clone -f src2 dst

Or alternatively, for this simple case, you could have said:

clone src2 dst
clone src1 dst

To clone an SCCS project tree, such as /pub/EOS_client_server, one might use the following command, shown with the resulting output:

doc% clone -S -v /pub/EOS_client_server ~/EOS_CS
clone: created new output directory: /home/ebupsn/EOS_CS
clone: created new output directory: /home/ebupsn/EOS_CS/bin
clone: created new output directory: /home/ebupsn/EOS_CS/lib
clone: created new output directory: /home/ebupsn/EOS_CS/include
clone: created new output directory: /home/ebupsn/EOS_CS/cmd
clone: created new output directory: /home/ebupsn/EOS_CS/cmd/clone
clone: created symlink /home/ebupsn/EOS_CS/cmd/clone/SCCS -> /pub/EOS_client_server/cmd/clone/SCCS
clone: created symlink /home/ebupsn/EOS_CS/cmd/SCCS -> /pub/EOS_client_server/cmd/SCCS
clone: created new output directory: /home/ebupsn/EOS_CS/man
clone: created new output directory: /home/ebupsn/EOS_CS/man/man1
clone: created new output directory: /home/ebupsn/EOS_CS/man/man3
clone: created new output directory: /home/ebupsn/EOS_CS/man/cat1
clone: created new output directory: /home/ebupsn/EOS_CS/man/cat3
clone: created symlink /home/ebupsn/EOS_CS/SCCS -> /pub/EOS_client_server/SCCS

CAVEATS
On BSD systems, if there are symbolic links in the source tree, the effects of cloning may not be what you expect. A symbolic link within the source tree results in the creation of an identical symbolic link within the destination tree. A warning is issued if the symbolic link is either absolute and points into the source directory or if the symbolic link is relative and points out of the source tree.

If the -S option is in effect and the source directory is itself a symbolic link to a directory, the contents of the symbolic link are cloned in the destination directory rather than setting the destination directory to be an identical symbolic link. The rational for this is as follows. In networked environments, SCCS project directories are often configured as NFS file systems managed by an NFS auto-mount daemon. The NFS auto-mount daemon mounts NFS file systems in a temporary locations and then creates symbolic links to the temporary locations. Accesses to this symbolic links trigger the NFS auto-mount daemon. It is therefore necessary that symbolic links in the destination tree refer to the NFS auto-mount point symbolic link rather than to the NFS auto-mount point itself. Symbolic links within the source tree are ignored.

WARNINGS
There are numerous possible warning and/or error messages which clone will issue for strange circumstances. These should all be self-explanatory.

FILES
/usr/local/bin/clone    The clone program

SEE ALSO
ln(1), link(2), symlink(2), readlink(2), mkdir (1), mkdir (2)

AUTHORS
Written by Ron Guilmette at the Microelectronics and Computer Technology Corporation. Current E-mail address is rfg@ics.uci.edu.

SCCS mode added 07-April-1993 by Paul Stephenson at Ericsson Business Communications. Current E-mail address is paul.stephenson@ebu.ericsson.se.