home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 11 Util / 11-Util.zip / utlos2.zip / Doc / ccp.doc next >
Text File  |  1998-02-07  |  12KB  |  255 lines
  1. $Id: ccp.doc 1.13 1998/02/08 02:02:01 brian Exp $
  2.  
  3.                          ccp : Conditional Copy
  4.                             By: Brian Yoder
  5.  
  6.         (c) Copyright International Business Machines Corporation 1998
  7.         All rights reserved.
  8.  
  9. The ccp command conditionally copies files to a target directory if they
  10. are missing from the target directory or have a different size, time, or
  11. date on the target directory. It preserves the name, read/write mode
  12. (read-only attribute), system and hidden attributes, and modification
  13. date and time of the files that it copies. It can also copy entire
  14. subdirectory trees as XCOPY /S does or just portions of subdirectory
  15. trees.
  16.  
  17. ========================================================================
  18. Command syntax
  19. ========================================================================
  20.  
  21.         ccp [ -flags ] [ -- ] source ... [ ! Xsource ... ] targetdir
  22.  
  23. The ccp command conditionally copies files whose names match the source
  24. file specification(s). It ignores hidden and system files. It copies
  25. files to the target directory. The target directory must exist.
  26.  
  27. If there is only one source file specification and no Xsource file
  28. specifications, then the targetdir is optional. In this case, it
  29. defaults to . (a dot, which means the current directory).
  30.  
  31. A source file specification consists of an optional drive, an optional
  32. path, and a filename. The filename can contain pattern-matching
  33. characters (see the pattern.doc file for a complete description of
  34. patterns in a filename). If a source file specification is a directory,
  35. then ccp appends "\*" to it, matching all files in the directory.
  36.  
  37. If a ! is specified, then ccp will exclude (not copy) any source file
  38. whose source name matches one of the Xsource patterns (listed between
  39. the ! and the target directory). Each Xsource pattern must match the
  40. full source name to exclude the source file. An Xsource pattern may, of
  41. course, contain drive and path information.
  42.  
  43. Generally, an Xsource pattern should start with a "*" character or with
  44. the drive and path of a source file (as specified on the command line)
  45. or it will not exclude any source files. This is because ccp compares
  46. each Xsource pattern with the path and name of each source file as it
  47. was specified on the command line, and including any subdirectory names
  48. that ccp added due to the -s flag. See the examples for more details.
  49.  
  50. Both \ (backslash) and / (forward slash) characters are interpreted as
  51. path separators in source file specifications, the Xsource (exclude
  52. source) patterns, and the target directory specifications. Therefore,
  53. the \ (backslash) character cannot be used as an escape character in an
  54. Xsource pattern.
  55.  
  56. This program writes the names of source files (both those copied and, if
  57. the x flag is specified, those excluded) to standard output. It writes
  58. all other messages, errors, and copy count statistics to standard error.
  59.  
  60. ========================================================================
  61. Flags
  62. ========================================================================
  63.  
  64. Normally, ccp only copies a source file if it is missing from the target
  65. directory, has a different size on the target directory, or has a
  66. different modification date and time on the target directory.
  67.  
  68. The behavior of ccp can be altered by one or more flags. All flag
  69. characters must follow the "-" and must be contiguous (no intervening
  70. spaces). The following flag characters are supported:
  71.  
  72.     -l  (letter el) If a file with the same name as a source file exists
  73.         in the target directory, copy the source file only if its
  74.         modification time is later than that of the file in the target
  75.         directory. In other words, only copy source files that are
  76.         later than those in the target.
  77.  
  78.     -d  If the target directory doesn't already exist, create it before
  79.         attempting to copy any files to it. The ccp program creates any
  80.         path components within the target directory that don't already
  81.         exist.
  82.  
  83.     -e  If a file with the same name as a source file doesn't exist in
  84.         the target directory, then don't copy the source file. In other
  85.         words, only copy files that already exist in the target.
  86.  
  87.     -f  Force copy even if target file is read-only.
  88.  
  89.     -n  Just display the names of source files that would have been
  90.         copied, but don't actually copy any files. If the -d flag is
  91.         also specified and the target directory doesn't exist, then the
  92.         target directory is also not actually created.
  93.  
  94.         The -n flag is an excellent way to see just what files would be
  95.         copied and which files would be excluded without actually
  96.         copying anything.
  97.  
  98.     -s  Descend subdirectories while searching for files to copy, just
  99.         as XCOPY /S does. The subdirectory structure (relative to the
  100.         source directory) is preserved within the target directory.
  101.         When a file is copied, any subdirectories that don't already
  102.         exist within the target directory are created by ccp.
  103.  
  104.         If the specified target directory doesn't exist, it is not
  105.         created unless the -d flag is also specified. The -s flag by
  106.         itself only creates subdirectories within the target directory
  107.         but never creates the target directory.
  108.  
  109.     -t  For each file copied, show the path and name of each target file
  110.         in addition to the path and name of each source file, as
  111.         follows:
  112.  
  113.                 sourcename -> targetname
  114.  
  115.     -x  Also display the names of source files that are being excluded
  116.         (not copied). One of the following characters is displayed in
  117.         front of each filename that ccp is excluding from copying:
  118.  
  119.         ! before files that you want to exclude (via ! Xsource ...).
  120.         x before files that ccp decides to exclude (not copy).
  121.  
  122.     -S  Also copy system and hidden files.
  123.  
  124.         Since system files are quite often also read-only files, the -S
  125.         flag should usually be combined with the -f flag to force
  126.         updates. Be very careful when updating system and hidden files!
  127.  
  128. ========================================================================
  129. Examples
  130. ========================================================================
  131.  
  132. ccp a:* .
  133.  
  134.         This command copies all files from the current directory on
  135.         drive A to the current directory if they don't exist in the
  136.         current directory or have a different size, date, or time in the
  137.         current directory.
  138.  
  139.  
  140. ccp a:*
  141.  
  142.         This command is the same as the previous one. Since there's only
  143.         one file specification, the target directory defaults to the
  144.         current directory.
  145.  
  146.  
  147. ccp * ! *.cod *xyz* a:
  148.  
  149.         This command conditionally copies all files in the current
  150.         directory, except for those whose names end with .cod or contain
  151.         xyz, to the current directory on drive A.
  152.  
  153.  
  154. ccp -sd c:\windows\* ! c:\windows\temp\* d:\archive\windows
  155.  
  156.         This command conditionally copies the c:\windows directory and
  157.         all of its subdirectories to the d:\archive\windows directory,
  158.         except for any files that are in the c:\windows\temp directory.
  159.         If any path components within the target d:\archive\windows
  160.         directory don't exist they are created before copying the files.
  161.  
  162.  
  163. ccp -sd c:\windows\* ! *temp* d:\archive\windows
  164.  
  165.         This command works like the previous command except it excludes
  166.         any files within c:\windows that contain temp in their name or
  167.         in any subdirectory of their name.
  168.  
  169.  
  170. ccp -sd c:\windows\* ! *\temp\* d:\archive\windows
  171.  
  172.         This command works like the previous command except it excludes
  173.         any files within c:\windows that also have a path component that
  174.         includes any "temp" subdirectory.
  175.  
  176.  
  177. ccp -sd c:\windows\* ! *\temp\* *sample.c d:\archive\windows
  178.  
  179.         This command works like the previous command except it excludes
  180.         any files within c:\windows that also have a path component that
  181.         includes any "temp" subdirectory, and it excludes any file named
  182.         "sample.c".
  183.  
  184.         Note that the exlusion pattern for sample.c begins with an
  185.         asterisk. This ensures that the pattern matches any file ending
  186.         in "sample.c" even if there is path or other information present
  187.         (such as test.sample.c).
  188.  
  189.  
  190. ccp -le * d:\tmp
  191.  
  192.         This command copies all files in the current directory to the
  193.         d:\tmp directory that already exist in d:\tmp but have a later
  194.         modification date and time than those in d:\tmp.
  195.  
  196.  
  197. ccp -n *.exe *.doc a:\
  198.  
  199.         This command displays the names of all of the .exe and .doc
  200.         files in the current directory that are missing from the root
  201.         directory on drive A or that have a different size, date, or
  202.         time in the root directory of drive A. No files are actually
  203.         copied.
  204.  
  205.  
  206. ccp -nelx * ! *.cod d:\mydir
  207.  
  208.         This command displays the names of files that would have been
  209.         copied, but doesn't actually copy anything.
  210.  
  211.         It looks at all files in the current directory, excluding any
  212.         that end in ".cod". It displays the names of the source files
  213.         (that it would have copied) that exist in the target directory
  214.         and that are later than their counterparts in the target
  215.         directory.
  216.  
  217.         Since you excluded the *.cod files, ccp displays the names of
  218.         the *.cod files with a "!" before each of their names. Since ccp
  219.         excludes files that either don't exist in the target directory
  220.         or have the same or earlier modification time in the source
  221.         directory, ccp displays these latter files with an "x" before
  222.         each of their names.
  223.  
  224.  
  225. ccp -st c:*.exe d:
  226.  
  227.         This command copies all of the .exe files within the current
  228.         directory and all of its subdirectories on drive c: to the
  229.         current directory on drive d:. If a subdirectory in which a
  230.         copied file doesn't exist in the target, ccp creates it. Note
  231.         that ccp creates subdirectories within the target only for files
  232.         that are copied.
  233.  
  234.         The -t flag tells ccp to show the path and name of each target
  235.         files that is copied as well as its source path and name. For
  236.         subdirectory copies, this provides feedback that lets you know
  237.         exactly where each source file is being copied.
  238.  
  239. ========================================================================
  240. Miscellaneous Notes
  241. ========================================================================
  242.  
  243. The pattern * matches any filename. The pattern *.* matches any filename
  244. that contains a dot. Note that *.* will not match a filename that
  245. doesn't contain a dot! This is important to remember! See the
  246. pattern.doc file for more details.
  247.  
  248. The handling of the archive attribute of a copied file varies depending
  249. upon the platform. The DOS version uses a custom open/read/write/close
  250. copy loop and copies all attributes exactly. The Win32 version uses the
  251. native Windows CopyFile() API function and also preserves the archive
  252. attribute. The OS/2 version uses the native OS/2 DosCopy() API function
  253. and always sets the archive attribute bit of the target file even if the
  254. source file's archive attribute is not set.
  255.