
                         TreeDo/Command line utility
          Traverses dir tree, performing supplied command in each dir.

                      mikel@speakeasy.org <Mike Lempriere>

Created Feb-93,
| This version 1.8, 18-Dec-96
[Vertical bar ("|") in left column indicates new/changed in this revision.]

------------------------------------------------------------------------------

WHAT IT DOES:

  TREEDO is a simple command line program that does a command through all
  subdirs, with some dir substitution capabilities and knowledge of MAKE.
| DOS, OS/2, WinNT:
    As an example, the following will delete all *.tmp files on C: drive:

      C:
      cd \
      treedo -v del *.tmp
|
| Unix:
|   As an example, the following will delete all "core" files here and below:
|   treedo rm core

|It can be used like the unix "find . -name -exec rm {} \;", but is a
|heckuvalot easier to remember how to use, and allows the command to work
|out of the target directory instead of having to handle a full path.

------------------------------------------------------------------------------

INSTALLATION:

  Merely unpack TREEDO.ZIP, then move TREEDO.EXE to a dir on your path.
  I'd recommend moving TREEDO.TXT (this file) to the same dir so you can
  find it later (unless you have a dir of loose docs, put it there).

  If you have an earlier version of TreeDo, you can safely overwrite the
  older files with new; none have been obsoleted, all have been replaced.

  TREEDO is a C++ program; the complete source file TREEDO.CPP is included
  in the zip file in case you're inclined to look at the source, as is a
  simple Makefile for building it.  There is also a simple .RC file, and
  a .ICO file to supply it an icon.  These are only needed to build the
  program, they are not needed to run it.

------------------------------------------------------------------------------

LICENSE JUNK:

  There are no requirements for using this program.

  Of course there are also no warranties.

  You may redistribute treedo freely, as long as all files go together;
| treedo.exe, treedo, treedo.cpp, treedo.txt, treedo.rc, treedo.ico,
| Makefile, makefile.dos, file_id.diz.

  I do ask, however, that if you have Internet e-mail access you drop me
  a line of thanks or criticism.  Also indicate in your mail if you'd like
  to be notified of any future renditions.

  If you find a bug, please e-mail me about it.  If you make any mods to
  the source, please e-mail them to me so that I can incorporate them into
  any future renditions.  If you have any suggestions for improvements to
  TREEDO, I'd especially like to hear them, e-mail me; mikel@speakeasy.org.

------------------------------------------------------------------------------

USAGE:

  I wrote this program originally to perform a MAKE in all subdirs so as to
  build a large software product in an automated fashion.  However, it's
  not tied to make, I left it generic so that it can perform any command
  supplied in all subdirs.

  A very simple example of what it does, is to simply type:

      C:
      cd \
      treedo cd

  It will then perform the CD command in each dir on your C: drive, thus
  listing them all out to your screen.  (It's fine to hit ctrl-C if you
  don't want to watch them all go by.)

  It can be started anywhere without actually having to CD there (-s),
  display each dir as it goes (-v), only execute at a lowest level dir (-l),
  only go into dirs with a certain file (-e), or only go into dirs with a
  specific text file containing a specific command (-m).  It can supply the
  drive and/or dir of the dir it's working in to the command (%d, %p).  And
  of course, it can take any command.  It can also dup2() stderr to stdout.

------------------------------------------------------------------------------

COMMAND SUMMARY:

  Usage: [switches] command [args]
  Switches:
  -h,-?	This Usage screen.
  -v	Verbose mode -- displays each dirname before performing command.
  -o	dup Output mode -- copies stderr to stdout.
  -l	Leaves only mode -- Only performs command in bottommost dirs.
  -n	no recurse -- does not go into subdirs.
  -s p	Set initial drive & dir.
  -M f r Special check for 'make'.  This checks each dir for file 'f', and, if
	it exists, checks for rule 'r' in that file.  If both conditions
	are met, treedo performs the given command, else dir. will be skipped.
	Note that 'rule' is assumed to be anchored left, and is a simple
	char-by-char match (no wildcards) -- not a Regular Expression!
	Sample: treedo -v -m makefile.dos lib make -f makefile.dos lib
  -m r	Same as "-M" but assumes file is "Makefile".
	Also, if no command supplied, assumes command is 'make' with a 1st
	arg of 'r'.  Sample:  "treedo -m clean" does a "make clean" in every
	dir with a "makefile" file containing a "clean" rule.
  -e f	Check for file existance.  This checks each dir for file 'f', and, if
	it exists, performs the given command, else dir. will be skipped.
  -p n s Substitutes Path segment 'n' with 's'.  Sample: in the C:\Prima\Src
	dir:  treedo -n -p 1 Foo echo S:%p  displays S:\Foo\Src

  Special args:
| %d	current working drive [ignored in unix]
  %p	current working directory (without drive)
  %i	initial working directory
  %s	starting directory (1st parm after -s)
  %m	makefile name (1st parm after -m) (-m mode only)
  %r	makefile rule (2nd parm after -m) (-m mode only)

  All unrecognized args will be passed to the new subshell as the command
  to perform and its args.

------------------------------------------------------------
  EXAMPLES:

    Get a file listing for all dirs below this one:

        treedo dir > dirlist.txt


    For every dir below this one, if there is a 'makefile.dos',
    and it has a 'lib:' rule, perform that make, displaying each
    dir name as we go, with stderr in the redirected output file:

        treedo -o -v -m makefile.dos lib: make -f makefile.dos lib > make.err


    Delete every file named 'core' on the entire D: drive, without
    bothering to go there first:

        treedo -s D:\ -e core del core


    Duplicate dir structure on D: drive:

        treedo -v mkdir D:%p

    Duplicate dir structure on D: drive, changing name of top level
    dir to "dup":

        treedo -p1 dup mkdir D:%p


    Send current drive and dir to a command as args:

        treedo -n echo %d %p


    Dup stderr to stdout for compile/link output redirection:

        treedo -o -n bcc -Dos2 treedo >treedo.err

        (This is the same as)
        bcc -Dos2 treedo 2>&1 > treedo.err
        (under OS/2, but is not possible under DOS.)


    Find all files named config.sys on drive D:

        treedo -v -s D:\ dir /b config.sys 2>nul


    For every dir under this one, if it has a normal old "makefile"
    with a "clean" rule, perform that clean:

        treedo -m clean


------------------------------------------------------------------------------

PORTING:

  The original DOS code compiled fine under Borland's OS/2 compiler by adding
  a "-Dos2" to the command line and some trivial "#ifdef"s.  Unfortunately,
  DOS compatibility was lost in porting to IBM's CSET++, as it now uses the
  OS/2 DosFindFirst() call directly, instead of Borland's 'find_t' struct and
  _dosfindfirst() call.  As I no longer have access to a Borland DOS
  compiler, I'm not able to go back and get the DOS rendition working.
  (Note: Courtesy jernst@vnet.ibm.com, the supplied source has been confirmed
  to compile/link/run on DOS under Borland 3.1.)

| The supplied .exe was built with IBM CSET++ 2.0  The source has also been
| compiled/linked/used extensively under Borland's C++ 1.00 for OS/2.
| The supplied Unix executable was built with DEC's cxx Ver. 50190001.

  It was originally written under DOS (Borland 3.1 compiler), to deal with
  Borland compiler/linker/librarian etc. output, which write some output to
  stdout, and some to stderr.  As DOS has no way of combining the two
  streams from the command shell, TREEDO does this for all child processes
  by means of dup2(1, 2) if the -o switch is supplied.  Under OS/2 this
  functionality is less important as "2>&1" works in the command shell.

  If you do get it to compile on any compiler not mentioned, please let me
  know (e-mail mikel@speakeasy.org), especially if you had to make changes.
  If you try to compile it on any compiler and fail, please let me know,
  I'd be glad to help try to make it work.

  The included Makefile has commented out lines in it for Borland, just
  edit it, commenting out the IBM CSET lines, uncommenting the Borland.
  You can also use "make clean" to get rid of the .obj, .map, etc. files.

  The code compiles warning free.  If you get warnings from some other
  compiler, I'd love to have them fixed, please let me know, and I'll
  include your fixes in future revisions.

------------------------------------------------------------------------------

REVISION HISTORY:

| Ver 1.8: submitted to Hobbes 18-Dec-96
|   a)  Note new e-mail address!
|   b)  Port to DEC's Digital Unix.
|   c)  Lower-cased filenames for convenience in Unix world.
|
| Ver 1.7: Never submitted to Hobbes
|   a)  Port to MS BackOffice for Windows NT.
|
  Ver 1.6: submitted to Hobbes 07-Jul-95
    a)  Fixed -e mode which I seem to have broken last time.

  Ver 1.5: not submitted to hobbes
    a)  Fixed oopsey where -p switch would leave garbage chars in %p.
    b)  Made it now append a colon to the given rule so that "-m"
        would only match the given rule exactly; eg. "treedo -m exe"
        used to match an "execln:" rule.  Now only matches "exe:" rule.
    c)  Added conditionals in Makefile.

  Ver 1.4: submitted to Hobbes 18-Apr-95
    a)  Changed to now include the top-level dir, it used to NOT do the
        initial working dir.
    b)  Made file first/next stuff into a C++ class to localize the
        #ifdef os/2 vs. dos ugliness.
    c)  The 1.3 submission yesterday burned with a "disk full" error,
        leaving an empty file behind.  Due to this, I'm leaving the 1.3
        changes highlighted ("|") in this doc.
    d)  Added new files TreeDo.ico and TreeDo.rc to build in an icon.

  Ver 1.3: submitted to Hobbes 05-Apr-95
    a)  Changed "-m" switch to pre-make the command line if none supplied.
        As an example:
            treedo -v -m clean make clean
        can now have the command and makerule simply dropped:
            treedo -v -m clean
    b)  Added "-p" switch to allow substitution of a single segment in
        the resolved "%p" path.
    c)  Updated this doc.  Note especially new e-mail address for me!

  Ver 1.2: submitted to Hobbes 27-Dec-94
    a)  Added an fflush() to force -v output to come out at the expected
        place when combined with stderr.  This was not necessary with
        Borland standard C libs (but won't hurt), and is necessary with
        IBM CSET++ standard C libs.
    b)  Changed existing "-m" to "-M", and fixed "-m" to work just like
        "-M" but with the default filename "Makefile".

  Ver 1.1: submitted to Hobbes 26-Nov-94
    a)  Fixed supplied Makefile for platform independence.
    b)  Usage message filled in.
    c)  Accompanying text (.pkg, .txt) written.

  Ver 1.0:  Personal use only, never released.
