File Spreader
-------------

This program moves files by groups into subdirectories.

Things can get very slow if you have a large number of files all in one
directory. SPREAD allows you to move those files into subdirectories each
containing a subset group. This can make searching and working with the
files a lot faster especially for programs that continually scan or count
files in the directory.

There are two methods that can be used to group the files; alphabetical and
number.


1. ALPHABETICAL GROUPS

 Syntax:
 SPREAD <mask> /A [/R] [/V]

 Example:
 SPREAD "C:\MY DOCUMENTS\*.TXT" /A

 The Alpha method looks at the file names and groups them into directories
 by the first alphabetical character of the name. This method ignores all
 leading punctuation and numbers so "2004_VACATION.JPG" and
 "VACATION_2004.JPG" both go into the "V" directory.

 Two special cases are for file names that start with "A" and "THE"
 followed by at least one space, underscore or dash character. These very
 common words are ignored unless there are no other alphabetical characters
 in the file name. This helps to avoid over crowding in the "A" and "T"
 directories.

 If the file name contains no letters, then the first non-Zero number is
 used unless Zero is the only number. If the file name is only punctuation,
 then the first character of the file name is used.

 It is important to note that this method has a maximum limit on the number
 of subdirectories (26 letters, plus 10 numbers, plus the punctuation valid
 in a file name) which may cause a large number of files to end up in some
 directories while others only have a few.

 If a file exists with a single character name matching a directory name
 that file will be moved inside the directory of the same name. This means
 a file named "X" will be automatically moved into the X directory.

 The file group number and pack options (see below) have no effect on the
 alphabetical method.

2. NUMBER GROUPS

 Syntax:
 SPREAD <mask> <number> [/P] [/R] [/V]

 Example:
 SPREAD "C:\MY DOCUMENTS\*.TXT" 1000 /P

 The Number method creates a series of numbered directories and puts a
 group of files into each directory. This method is useful when all of the
 files have similar names like digital camera pictures with raw file names.

 There is no practical limit to the number of subdirectories this method
 can create. The subdirectory counting starts at zero (0) and increments up
 adding as many digits as needed to each additional subdirectory name for
 each group of files.

 Existing number subdirectories are skipped even if they are empty unless
 the optional pack (/P) switch is used. The pack command line switch can be
 used to go back and make sure all of the existing numbered subdirectories
 each have the maximum number of files as specified on the command line.

 The Pack switch is useful over time as new files are added or when
 shifting from alphabetical to numbered method, but continually rescanning
 the existing directories can take a long time if they contain a large
 number of files or if there are a large number of directories. Directory
 re-scanning is only performed once each time this program is run with the
 Pack switch to help avoid some of the performance impact.


Alphabetical Method Syntax:

 SPREAD <mask> /A [/R] [/V]

 mask   = The path to the working directory and file name wildcard mask for
          the files to include in the scan. The default is to include all
          files. If the path or file name includes a space, double quotes
          must enclose the whole path and file name mask.

 /A     = Group files into directories based on first alphabetical, number
          or punctuation character. Letters are used first. If no letters
          are found in the file name, numbers are used. If no letters and
          no numbers are found in the file name, the first punctuation
          character of the file name is used.

 /R     = Rename mode. Renames all conflicting file names destined for the
          same subdirectory. If there is a name conflict, a number in
          between square brackets is added to the end of the root file
          name (before the file extension). This method of avoiding name
          conflict is also used by other IFX Group file management tools
          like the FIXNAME utility available from the IFX Group web site.
          The default is not to move any files with conflicting names.

 /V     = Verbose mode. Shows extra information about the internal
          processing on the screen. This can be helpful for debugging and
          may be redirected to a file for later review using the standard
          command line redirection methods.
Number Method Syntax:

 SPREAD <mask> <number> [/P] [/R] [/V]

 mask   = The path to the working directory and file name wildcard mask for
          the files to include in the scan. The default is to include all
          files. If the path or file name includes a space, double quotes
          must enclose the whole path and file name mask.

 number = The maximum number of files to put into each subdirectory. If
          this number is not given or is zero, the default is 2500. A
          series of numbered subdirectories (starting with zero) are
          created to hold each group of files.

 /P     = Optionally pack maximum number of files into existing number
          directories before creating new subdirectories.

 /R     = Rename mode. Renames all conflicting file names destined for the
          same subdirectory. If there is a name conflict, a number in
          between square brackets is added to the end of the root file
          name (before the file extension). This method of avoiding name
          conflict is also used by other IFX Group file management tools
          like the FIXNAME utility available from the IFX Group web site.
          The default is not to move any files with conflicting names.

 /V     = Verbose mode. Shows extra information about the internal
          processing on the screen. This can be helpful for debugging and
          may be redirected to a file for later review using the standard
          command line redirection methods.


 Press Ctrl-C to abort the program at any time while it is running.

Copyright by Casey Sprangel, all rights reserved. The fully commented
PowerBASIC/CC source code has been included for your educational use. The
latest version of this program and many other useful tools can be found at
WWW.IFXGROUP.NET.

