dv-file [-R]      list registered files at or beneath CWD
   dv-file [-bfnqRv] relpath...            register source files
   dv-file -m[fnqRv] relpath... destpath  move source files
   dv-file -c[fnqRv] relpath... destpath  copy source files
   dv-file -u[qv] relpath...              unregister source files
   dv-file -X[fnqRv] relpath...           delete source files

   dv-file -L                  list defined source file types
   dv-file -G type relpath...  generate source files from a template
   dv-file -U type relpath...  update source files from a template

 where: 
   relpath can be any of the following:
      a) an explicit file path relative to CWD
      b) --find='glob' specifies a filename search pattern
      c) a directory path relative to CWD, representing eligible files
         that it contains (possibly extended recursively with -R)
      The find argument operates recursively on the CWD if no
      other relpath arguments are specified.
      CWD = current working directory

  destpath = desired new file path (relative to CWD)
             (can be a parent directory path)

 -b   registers files as being BINARY, thereby activating special
      handling when locked and committed (disables RCS variable
      expansion)
 -f   allows source area owner to override restrictions
 -h   displays this usage message
 -n   noop mode - lists what would be performed
 -q   quiet output mode
 -R   extend operation recursively into subdirectories
 -v   verbose output mode

This script manages source files that exist in the current source area, and that are mirrored in the current build area. All work with this script takes place within a current source and build area. Change your current working directory accordingly before using this script. Use dv-sync to propagate these changes to other build areas.

Use this script to create, register, and move new source files within source and build areas, and to check for registered files that have not been committed. It can also be used to delete files, though only source area owners can delete files once they have been committed. Current source and build areas must be selected (as determined by localdev mode or via dv-select) before using this script.

When run without arguments, this script lists registered files at or below the current directory that have not been committed. Some of these files may have been registered by others - the owners are indicated.

Files are always specified as pathnames relative to the current working directory (CWD). When moving or copying files, the destination can be specified as either an existing parent directory or as the new file path.

A file need not exist in order for you to register it. You can think of registering a file as putting a placeholder for the file into the source area. This will indicate to others that you intend to commit the file, and will prevent others from doing so. Files can be registered at any time that the source area is on-line. Read-only files are only registered if the force option (-f) is used. If you register binary files, be sure to use the binary option (-b). This causes them to be handled specially when committed.

Each source area is configured with a list of filename patterns that are to be ignored (the filename-patterns-to-ignore property). This script will skip the registry or manipulation of a file whose name matches any of those patterns unless it is already registered. Run 'dv-config -s' to see a list of these patterns. The owner of a source area can configure these to match the needs of a project. Note that a source area owner can use the force option ('-f') to force registration in spite of a match.

Copy, move, and delete operations deal equally well with unregistered, registered, and committed files, subject to the ignored pattern match limitation described above. Each type of file is handled appropriately. A key requirement of this script is that only writable files are acted upon. Unstaged files or files staged with dv-stage, for example, would not be eligible, and would be skipped.

This script is sensitive to source area state. Committed files can be moved, copied, or deleted only if the source area is in a state that allows modifications, and only if you have locked them (with dv-lock). If the source area configuration allows, then use of the force option ('-f') will instruct this script to change source area state from 'closed' or 'stable' to 'open' in order to move or delete committed files. If a source area is in an offline state, then only the source area owner can affect committed files.

Any limitation that is encountered will cause this script to skip the processing of ineligible files and generate appropriate messages. A source area owner can override some of these limitations with the force ('-f') option, but only by naming the affected files on the command-line. Directory search, recursion, and find capabilities, described below, remain unaffected by the use of force.

This script supports a number of flexible options for selecting files without naming them explicitly. The ability of this script to skip processing of ineligible files makes it easy to use UNIX wildcard (glob) expansion syntax (like *.C) to specify multiple files. In addition, you can specify a directory to indicate all eligible files within it. If used with the recursion option ('-R'), then this extends recursively down through all directories beneath the one specified.

There is also a find option (--find='glob') that allows you to search recursively for eligible files whose names match a specified (glob) pattern. Glob patterns consist of the familiar syntax that UNIX shells use to select groups of files (*.C, for example). The glob pattern is placed in quotes so that it is not expanded by the shell before invoking this script. When this option is specified, any files found are added to the list of files to be processed.

The noop option ('-n'), causes this script to list actions that would be performed and then exit. This can be a good way to verify that desired actions will work as expected prior to taking them.

Whenever source files are moved or removed, links between source areas and their build areas are broken. These links can be updated by running dv-sync within each build area over each directory containing affected files. Note that this will also make any newly committed files appear within your build area.

WARNING: Don't try moving or copying registered or committed source files manually. It won't work without also performing additional, less convenient manual steps. Use this script to move or copy source files. This will ensure that the integrity of your source area is preserved.

This script also supports source file creation and update via template. Each source area can be configured with a directory containing source file type information and templates. These can be customized to meet the needs of individual sites and projects. You can list the defined source file types with the list option ('-l'). While use of templates is optional, it can save time if they are configured well.

When creating a file from a template, it is generated with a standard heading. Each heading consists of an opening fixed-format section, a configurable disclaimer, and a custom section that can be used for file-specific information. You can easily use the update feature of this script to generate a set of files having specialized disclaimers.