% $Id: ccp.tex 1.13 1998/02/07 19:40:11 brian Exp $

\chapter{ccp---Conditional Copy}

The \textbf{ccp} command conditionally copies files to a target
directory if they are missing from the target directory or have a
different size, time, or date on the target directory. It preserves
the name, read/write mode (read-only attribute), system and hidden
attributes, and modification date and time of the files that it
copies. It can copy entire subdirectory trees as \texttt{XCOPY /S}
does or just portions of subdirectory trees. It can also exclude files
and subdirectory trees that match one or more optional exclusion
patterns.

\section{Usage}

\verb+ccp [ -flags ] [ -- ] source ... [ ! Xsource ... ] targetdir+
\medskip

The \textbf{ccp} command conditionally copies files whose names match
the source file specification(s). It ignores hidden and system files.
It copies files to the target directory. The target directory must
already exist.

If there is only one \textit{source} file specification and no
\textit{Xsource} file specifications, then the \textit{targetdir} is
optional. In this case, it defaults to \texttt{.}\ (a dot, which means the
current directory).

A \textit{source} file specification consists of an optional drive, an
optional path, and a filename. The filename may contain
pattern-matching characters. If a \textit{source} file specification
is the name of a directory, then \textbf{ccp} appends ``\texttt{/*}''
to it, matching all files in the directory.

If a \textbf{!}\ is specified, then \textbf{ccp} will exclude (not
copy) any source file whose source name matches one of the
\textit{Xsource} patterns (listed between the \texttt{!}\ and the
target directory). Each \textit{Xsource} pattern must match the full
source name to exclude the source file. An \textit{Xsource} pattern
may, of course, contain drive and path information.

Generally, an \textit{Xsource} pattern should start with a
``\texttt{*}'' character or with the drive and path of a source file
(as specified on the command line) or it will not exclude any source
files. This is because \textbf{ccp} compares each \textit{Xsource}
pattern with the path and name of each source file as it was specified
on the command line, and including any subdirectory names that
\textbf{ccp} added due to the \texttt{-s} flag. See the examples for
more details.

Both \verb+\+ (backslash) and \texttt{/} (forward slash) characters
are interpreted as path separators in source file specifications, the
\textit{Xsource} (exclude source) patterns, and the target directory
specifications. Therefore, the \verb+\+ (backslash) character cannot
be used as an escape character in an \textit{Xsource} pattern.

This program writes the names of source files (both those copied and,
if the \texttt{-x} flag is specified, those excluded) to standard
output. It writes all other messages, errors, and copy count
statistics to standard error.

\section{Flags}

By default, \textbf{ccp} only copies a source file if it is missing from the
target directory, has a different size on the target directory, or has
a different modification date and time on the target directory.
The behavior of \textbf{ccp} can be altered by the following flags:

\begin{itemize}

   \item[\texttt{-l}] (letter el) If a file with the same name as a
        source file exists in the target directory, copy the source
        file only if its modification time is later than that of the
        file in the target directory. In other words, only copy source
        files that are later than those in the target.

   \item[\texttt{-d}] If the target directory doesn't already exist, create
        it before attempting to copy any files to it.

        Note that if you specify \texttt{-s} with or without
        \texttt{-d}, \textbf{ccp} always creates any path components
        \textit{within} the target directory that don't already exist.

   \item[\texttt{-e}] If a file with the same name as a source file doesn't
        exist in the target directory, then don't copy the source
        file. In other words, only copy files that already exist in
        the target.

   \item[\texttt{-f}] Force copy even if target file is read-only.

   \item[\texttt{-n}] Just display the names of source files that
        would have been copied, but don't actually copy any files. If
        the \texttt{-d} flag is also specified and the target
        directory doesn't exist, then the target directory is also not
        actually created.

        The \texttt{-n} flag is an excellent way to see just what
        files would be copied and which files would be excluded
        without actually copying anything.

   \item[\texttt{-s}] Descend subdirectories while searching for files
        to copy, just as \texttt{XCOPY /S} does. The subdirectory
        structure (relative to the source directory) is preserved
        within the target directory. When a file is copied, any
        subdirectories that don't already exist within the target
        directory are created by \textbf{ccp}.

        If the specified target directory doesn't exist, it is not
        created unless the \texttt{-d} flag is also specified. The
        \texttt{-s} flag without \texttt{-d} only creates
        subdirectories within the target directory but never creates
        the target directory.

   \item[\texttt{-S}] Also copy system and hidden files.

        Since system files are quite often also read-only files, the
        \texttt{-S} flag should usually be combined with the
        \texttt{-f} flag to force updates. Be very careful when
        updating system and hidden files!

   \item[\texttt{-t}] For each file copied, show the path and name of
        each target file in addition to the path and name of each
        source file, as follows:

        \begin{itemize}
        \item[{}]
        \verb+sourcename -> targetname+
        \end{itemize}

   \item[\texttt{-x}] Also display the names of source files that are
        being excluded (not copied). One of the following characters
        is displayed in front of each filename that \textbf{ccp} is
        excluding from copying:

        \begin{itemize}

        \item[{}]
        \texttt{!}\ before files that you want to exclude (via
        \texttt{!}\ \textit{Xsource}), and

        \item[{}]
        \texttt{x}
        before files that \textbf{ccp} decides to exclude (not copy).

        \end{itemize}

\end{itemize}

\section{Examples}

\begin{enumerate}

\item
\texttt{ccp a:* .}

        This command copies all files from the current directory on
        drive \texttt{A} to the current directory if they don't exist
        in the current directory or have a different size, date, or
        time in the current directory.

\item
\texttt{ccp a:*}

        This command is the same as the previous one. Since there's only
        one file specification, the target directory defaults to the
        current directory.

\item
\texttt{ccp * !\ *.cod *xyz* a:}

        This command conditionally copies all files in the current
        directory, except for those whose names end with \textbf{.cod}
        or contain \textbf{xyz}, to the current directory on drive
        \texttt{A}.

\item
\verb+ccp -sd c:\windows\* ! c:\windows\temp\* d:\archive\windows+

        This command conditionally copies the \verb+c:\windows+
        directory and all of its subdirectories to the
        \verb+d:\archive\windows+ directory, except for any files that
        are in the \verb+c:\windows\temp+ directory. If any path
        components within the target \verb+d:\archive\windows+
        directory don't exist they are created before copying the
        files.

\item
\texttt{ccp -sd c:/windows/* !\ *temp* d:/archive/windows}

        This command works like the previous command except it
        excludes any files within \textbf{c:/windows} that contain
        \textbf{temp} in their name or in any subdirectory of their name.

        Also notice that forward slashes work just as well as
        backslashes. Indeed, when running \textbf{ccp} (or any of
        these other commands) from within a Perl, Python, bash, gawk,
        or awk script, or from within another scripting language, a
        backslash is often used to start an escape sequence and a
        forward slash is a more convenient and robust path separator.

\item
\texttt{ccp -sd c:/windows/* !\ */temp/* d:/archive/windows}

        This command works like the previous command except it
        excludes any files within \textbf{c:/windows} that also have a
        path component that includes any \textbf{temp} subdirectory.

\item
\texttt{ccp -sd c:/windows/* !\ */temp/* *sample.c d:/archive/windows}

        This command works like the previous command except it excludes
        any files within \textbf{c:/windows} that also have a path component that
        includes any \textbf{temp} subdirectory, and it excludes any file named
        \textbf{sample.c}.

        Note that the exclusion pattern for \textbf{sample.c} begins
        with an asterisk. This ensures that the pattern matches any
        file ending in \textbf{sample.c} even if there is path or
        other information present (such as \textbf{test.sample.c} and
        \textbf{tempdir/sample.c}).

\item
\texttt{ccp -le * d:/tmp}

        This command copies all files in the current directory to the
        \textbf{d:/tmp} directory that already exist in
        \textbf{d:/tmp} but have a later modification date and time
        than those in \textbf{d:/tmp}.

\item
\texttt{ccp -n *.exe *.doc a:/}

        This command displays the names of all of the \textbf{.exe}
        and \textbf{.doc} files in the current directory that are
        missing from the root directory on drive \texttt{A} or that
        have a different size, date, or time in the root directory of
        drive \texttt{A}. No files are actually copied.

\item
\texttt{ccp -nelx * !\ *.cod d:/mydir}

        This command displays the names of files that would have been
        copied, but doesn't actually copy anything.

        It looks at all files in the current directory, excluding any
        that end in \textbf{.cod}. It displays the names of the source
        files (that it would have copied) that exist in the target
        directory and that are later than their counterparts in the
        target directory.

        Since you excluded the \textbf{*.cod} files, ccp displays the
        names of the \textbf{*.cod} files with a ``\texttt{!}''\ before
        each of their names. Since \textbf{ccp} excludes files that
        either don't exist in the target directory or have the same or
        earlier modification time in the source directory, ccp
        displays these latter files with an ``\texttt{x}'' before each
        of their names.

\item
\texttt{ccp -st c:*.exe d:}

        This command copies all of the \textbf{.exe} files within the
        current directory and all of its subdirectories on drive
        \texttt{C} to the current directory on drive \texttt{D}. If
        a subdirectory in which a copied file doesn't exist in the
        target, \textbf{ccp} creates it. Note that \textbf{ccp}
        creates subdirectories within the target only for files that
        are copied.

        The \texttt{-t} flag tells \textbf{ccp} to show the path and
        name of each target files that is copied as well as its source
        path and name. For subdirectory copies, this provides feedback
        that lets you know exactly where each source file is being
        copied.

\item
\texttt{ccp a:* .}

        This command copies all files from the current directory on
        drive \texttt{A} to the current directory if they don't exist
        in the current directory or have a different size, date, or
        time in the current directory.

\item
\texttt{ccp a:*}

        This command is the same as the previous one. Since there's only
        one file specification, the target directory defaults to the
        current directory.

\item
\texttt{ccp * !\ *.cod *xyz* a:}

        This command conditionally copies all files in the current
        directory, except for those whose names end with \textbf{.cod}
        or contain \textbf{xyz}, to the current directory on drive
        \texttt{A}.

\item
\texttt{ccp -sd c:/windows/* !\ c:/windows/temp/* d:/archive/windows}

        This command conditionally copies the \textbf{c:/windows}
        directory and all of its subdirectories to the
        \textbf{d:/archive/windows} directory, except for any files
        that are in the \textbf{c:/windows/temp} directory. If any
        path components within the target \textbf{d:/archive/windows}
        directory don't exist then \textbf{ccp} creates them before
        copying the files.

\item
\texttt{ccp -sd c:/windows/* !\ *temp* d:/archive/windows}

        This command works like the previous command except it
        excludes any files within \textbf{c:/windows} that contain
        \textbf{temp} in their name or in any subdirectory of their
        name.

\item
\texttt{ccp -sd c:/windows/* !\ */temp/* d:/archive/windows}

        This command works like the previous command except it excludes
        any files within \textbf{c:/windows} that also have a path component that
        includes any \textbf{temp} subdirectory.

\item
\texttt{ccp -sd c:/windows/* !\ */temp/* *sample.c d:/archive/windows}

        This command works like the previous command except it excludes
        any files within \textbf{c:/windows} that also have a path component that
        includes any \textbf{temp} subdirectory, and it excludes any file named
        \textbf{sample.c}.

        Note that the exlusion pattern for \textbf{sample.c} begins with an
        asterisk. This ensures that the pattern matches any file ending
        in \textbf{sample.c} even if there is path or other information present.

\item
\texttt{ccp -le * d:/tmp}

        This command copies all files in the current directory to the
        \textbf{d:/tmp} directory that already exist in
        \textbf{d:/tmp} but have a later modification date and time
        than those in \textbf{d:/tmp}.

\item
\texttt{ccp -n *.exe *.doc a:/}

        This command displays the names of all of the \textbf{.exe}
        and \textbf{.doc} files in the current directory that are
        missing from the root directory on drive \texttt{A} or that have a
        different size, date, or time in the root directory of drive
        \texttt{A}. No files are actually copied.

\item
\texttt{ccp -nelx * !\ *.cod d:/mydir}

        This command displays the names of files that would have been
        copied, but doesn't actually copy anything.

        It looks at all files in the current directory, excluding any
        that end in \textbf{.cod}. It displays the names of the source files
        (that it would have copied) that exist in the target directory
        and that are later than their counterparts in the target
        directory.

        Since you excluded the \textbf{*.cod} files, \textbf{ccp}
        displays the names of the \textbf{*.cod} files with a
        \texttt{!}\ before each of their names. Since \textbf{ccp}
        excludes files that either don't exist in the target directory
        or have the same or earlier modification time in the source
        directory, ccp displays these latter files with an \texttt{x}
        before each of their names.

\item
\texttt{ccp -st c:*.exe d:}

        This command copies all of the \textbf{.exe} files within the
        current directory and all of its subdirectories on drive
        \texttt{C} to the current directory on drive \texttt{D}. If
        a subdirectory in which a copied file doesn't exist in the
        target, \textbf{ccp} creates it. Note that \textbf{ccp}
        creates subdirectories within the target only for files that
        are copied.

        The \texttt{-t} flag tells ccp to show the path and name of
        each target files that is copied as well as its source path
        and name. For subdirectory copies, this provides feedback that
        lets you know exactly where each source file is being copied.

\end{enumerate}
