X-title: Change Directory with History.  Version 5.0  [Freeware]
X-author: Dave Kruger
X-FILE: CDH.ZIP published in SP82a







































                      Copyright (C) 1990-1993 Dave Kruger

     2                                                                   2


     COPYRIGHT STATEMENT
     ===================

     CDH Copyright (C) 1990-1993 by Dave Kruger.
     All rights reserved.

     CDH is free, but it is a copyrighted work and may be distributed only
     pursuant to this license.

     Permission is hereby granted to reproduce and disseminate so long as:

     (1)  No remuneration of any kind is received in exchange

     (2)  Distribution is without ANY modification to the contents of
          CDH.EXE or the accompanying documentation.

     No copy of CDH may be distributed without including a copy of this
     license.

     Any other use is prohibited without express, written permission in
     advance.


     DISCLAIMER
     ==========

     The information contained in this document is subject to change
     without notice.  This software and documentation are provided free of
     charge and without warranty of any kind.  No responsibility is
     accepted for errors contained in this documentation, or for
     incidental or consequential damages in connection with the
     furnishing, performance, or use of the software or documentation.


     TRADEMARKS
     ==========

     MS-DOS is a registered trademark of Microsoft Corporation.

     Windows is a trademark of Microsoft Corporation.

     Lotus and 1-2-3 are registered trademarks of Lotus Development
     Corporation

     Turbo C is a registered trademark of Borland International, Inc.

     4DOS is a registered trademark of JP Software Inc.

     UNIX is a registered trademark of UNIX System Laboratories Inc.

     3                                                                   3


                                    CONTENTS
                                    ========

                      Introduction.......................3
                      Installation.......................4
                      Synopsis...........................4
                      Description........................4
                      Options............................5
                      Environment Variables..............6
                      Examples...........................6
                      Enhancing Usability................7
                        4DOS and Aliases.................7
                        Batch Files......................8
                        Environment Variables............8
                      Hardware Requirements..............9
                      Diagnostics........................9
                      Bugs and Enhancements..............9
                      Version and History...............10


     INTRODUCTION
     ============

     This manual documents version 5.0 of the CDH (Change Directory with
     History) utility.

     CDH replaces CHDIR, the standard MS-DOS change directory command.
     CDH provides similar functionality to CHDIR, but also includes a
     directory history facility.

     CDH maintains a record of the last 23 directories visited in a plain
     text file called the history file.  You can change to a directory in
     the history file by referring to it by its numeric position in the
     file, or by specifying any part of its name that differentiates it
     from other directory names in the history file.

     CDH also supports a CDPATH environment variable.  If the wanted
     directory is not a subdirectory of the current directory, the paths
     in the CDPATH are searched to find the wanted directory.

     CDH differs functionally from MS-DOS's CHDIR command as follows:

     1.   If you invoke CDH without an argument, it changes to the
          directory specified by the HOME environment variable.

     2.   Unlike CHDIR, CDH changes directories across drives.  For
          example, if the current directory is C:\TMP, and you enter the
          command CDH D:\TC, CDH changes the current directory to \TC and
          also changes the current drive to D:.  This is equivalent to
          entering the two MS-DOS commands: CD D:\TC and D:.

     3.   CDH searches the CDPATH environment variable if the wanted
          directory is not in the current directory.

     4                                                                   4


     INSTALLATION
     ============

     The only installation necessary to use CDH is to copy the CDH.EXE
     file to a directory in your PATH.

     You can customise the installation by defining environment variables,
     aliases, modifying COMMAND.COM, and so on; these are explained in the
     ENHANCING USABILITY section below.


     SYNOPSIS
     ========

     CDH [<dir>] [-?] [-H] [-L] [-V] [-] [-<pattern>] [-<number>]


     DESCRIPTION
     ===========

     The brackets in the synopsis above indicate that the argument is
     optional, therefore, all arguments are optional.  CDH takes a single
     argument only, or no argument at all.  There are two types of
     arguments: minus (-) options and directory names.  Arguments preceded
     by a "-" cause the current directory to change depending on what
     follows the "-".  Anything else is assumed to be a directory name
     that you want to change to.  Case is not significant for any
     argument; CDH sees no difference between -V and -v.  Similarly, the
     following <pattern>s are treated identically: -SnEg, -SNEG, and -sneG.

     If you invoke CDH without any arguments, it changes to the directory
     specified in the HOME environment variable (if set) or to the root
     directory on the current drive.

     The last 23 directories visited are recorded, in plain text, in the
     history file.  You can specify the name of the history file with the
     CDHISTFILE environment variable.  If CDHISTFILE is not set (or is set
     to an invalid path), the directory history is written to C:\CDHIST.
     If you change to a directory that is not in the history file, CDH
     inserts the new directory at position zero in the history file and
     moves all existing directories up by one position.  If the history
     file already contains 23 entries, CDH inserts the new directory at
     position zero in the history file, moves all existing directories up
     by one position, and deletes the oldest directory from the history
     file.

     You can edit the history file with any text editor, for example, EDIT
     or EDLIN.  You might want to edit the history file, for example, to
     delete entries for directories that no longer exist, or to delete
     references to directories on floppy drives.  The directory history is
     stored in uppercase in the history file.

     5                                                                   5


     You can access a directory in the history file by referring to its
     numeric position in the file, using -<number> as an argument, for
     example, CDH -15; or you can specify any part of a directory name
     using -<pattern> as an argument, for example, CDH -NEG.  Note,
     however, that <pattern>s must be at least two letters long to avoid
     confusion with other "-" options.

     When you invoke CDH with a valid directory name (<dir>) as an
     argument, CDH changes to <dir>.  <dir> can be in the current
     directory or in any directory in the CDPATH.


     OPTIONS
     =======

     <dir>      Changes to directory <dir>.  If <dir> does not exist in
                the current directory, CDH searches the directories
                specified in the CDPATH environment variable.  If <dir> is
                invalid after these searches, CDH prints an error message.

     -?         Prints a usage message like the synopsis above.

     -H         Prints an extended help message.

     -L         Lists the contents of the history file and the numeric
                position of each entry in the file.  This option is useful
                to determine whether a particular directory is in the
                history file, and to find its relative position.  You can
                then use CDH -<number> to change to the directory if it is
                in the history file (the -<number> option is described
                below).

     -V         Prints the version number of the CDH that you are using.

     -          Changes to the previous directory in the history file.

     -<pattern> Changes to the first directory in the history file that
                contains <pattern> anywhere in its path name.  If no entry
                contains <pattern>, CDH prints an error message.

     -<number>  Changes to the directory that is at the <number>th
                position in the history file.  You can find out the
                relative number of the directories in the history file by
                using the -L option described above.  If you enter a
                number greater than that reported with the -L option, CDH
                assumes that it is a <pattern>, and searches the history
                file for a directory that has <number> in its path name.

     6                                                                   6


     ENVIRONMENT VARIABLES
     =====================

     By default, CDH calls the history file CDHIST, and creates it in the
     root directory of the C drive.  If you don't like these defaults, you
     can set the CDHISTFILE environment variable to the path and file name
     you prefer.  If the value of CDHISTFILE is invalid, CDH uses the
     default values.

     When you invoke CDH with no arguments, it checks for the existence of
     the HOME environment variable.  If HOME is set to a valid path name,
     CDH changes to that directory.  If HOME is not set, CDH changes to
     the root directory of the current drive.  If HOME is set to an
     invalid path, CDH prints an error message and the current directory
     is not changed.

     The CDPATH environment variable is a list of pathnames separated by
     semicolons, similar to the standard MS-DOS PATH.  If the directory
     specified by a <dir> argument does not exist in the current
     directory, CDH searches each directory in the CDPATH in turn and
     changes to <dir> if it is found to be a subdirectory in any of them.
     See below for an example of using the CDPATH.

     The best place to set these environment variables is in your
     AUTOEXEC.BAT file so they are set each time you boot your computer.


     EXAMPLES
     ========

     CDH -L    Lists directories in the history file.  The examples that
               follow assume that this command reports the following:

                    3 D:\TC\INCLUDE
                    2 C:\USR\DAK\C
                    1 C:\TMP
                    0 C:\123\WKS

               The examples also assume that the CDPATH environment
               variable is set as follows:

                CDPATH=C:\USR\DAK;D:\TC;C\

               The current directory is C:\123\WKS.

     CDH -     This command changes to the C:\TMP directory.

     7                                                                   7


     CDH QUIN  Assuming that QUIN is not a subdirectory of C:\TMP, CDH
               searches the directories in the CDPATH and changes to
               QUINCE, which is a subdirectory of C:\USR\DAK.  A CDH -L
               command would now report the following:

                    4 D:\TC\INCLUDE
                    3 C:\USR\DAK\C
                    2 C:\123\WKS
                    1 C:\TMP
                    0 C:\USR\DAK\QUINCE

     CDH -In   Changes to first directory in history file that contains
               the pattern IN.  The current directory would now be
               D:\TC\INCLUDE.  Note that case is not significant in search
               patterns, and that the current directory is ignored in
               history searches.

     CDH -4    Changes to the fourth directory in the history list, that
               is, C:\USR\DAK\C.  (After the last example, entry zero in
               the history file was D:\TC\INCLUDE, and all other entries
               were moved up one position, therefore, C:\USR\DAK\C was
               then entry four in the history file.)


     ENHANCING USABILITY
     ===================

     As pointed out above, installation is as simple as copying CDH.EXE to
     a directory in the PATH.  However, there are some things you can do
     to enhance CDH's usability.  None of these are necessary, but they
     can make CDH even more useful.

     4DOS and Aliases:
     -----------------

     4DOS, by JP Software, is a replacement for the standard MS-DOS
     command processor, COMMAND.COM.  It is the single most useful
     enhancement you can apply to MS-DOS.  While maintaining 100%
     compatibility with COMMAND.COM, 4DOS provides many useful and
     powerful enhancements.  (4DOS, Version 5.0 does provide a directory
     history function, but the history is lost at each reboot.)  If you
     don't have 4DOS yet, you should--it's the best thing to happen to
     MS-DOS since hard disk support.  (I don't have any affiliation with
     JP Software.  I am merely a very satisfied, registered user.)

     4DOS provides an alias function that allows you to create your own
     commands or to effectively change the names of existing commands.  I
     use the following 4DOS aliases with CDH:

          ALIAS CD=C:\BIN\CDH
          ALIAS B=C:\BIN\CDH -
          ALIAS DL=C:\BIN\CDH -L

     8                                                                   8


     No matter how I try, I cannot get into the habit of typing CDH
     instead of CD, hence the first alias above.  "B" changes "Back" to
     the previous directory; "DL" is mnemonic for "Directory List".

     Several other programs provide an alias function, including ANARKEY
     (where they are called AKAs), CED (synonyms), and the standard
     MS-DOS utility, DOSKEY (macros).  All three allow you to bypass the
     internal CD command with an alias.  Refer to the documentation that
     comes with these products for information about defining aliases.

     Batch Files:
     ------------

     If you don't have access to an alias facility and you are using a
     version of MS-DOS prior to 5.0, you can write small batch files to
     provide the same functionality.  The above three aliases can be
     implemented in batch files as follows:

          CD.BAT              B.BAT               DL.BAT
          ------              -----               ------
          @echo off           @echo off           @echo off
          c:\bin\cdh.exe %1   c:\bin\cdh.exe -    c:\bin\cdh.exe -l

     The problem here though, is that the CD command is internal to
     COMMAND.COM, and will always be executed before CD.BAT.  To
     successfully implement CD.BAT you must use a binary editor to edit
     COMMAND.COM and change CD to CX (or another two letters).  You can
     use FED (an excellent utility) to do this.  Search for "CD" and look
     for an occurrence that is near "CHDIR", "MKDIR", and "RMDIR".  I'll
     leave the details for you to figure out, but it's only an issue when
     you want to use "CD" to refer to CDH and you don't have an alias
     facility.

     NOTE:     IF YOU DECIDE TO ALTER COMMAND.COM, DO NOT OPERATE ON THE
               ORIGINAL VERSION OF THE FILE.  ALWAYS MAKE SUCH CHANGES ON
               A COPY OF THE FILE ONLY.

     Environment Variables:
     ----------------------

     There are three environment variables of significance to CDH.

     The HOME environment variable is useful if you are in the habit of
     storing your personal files in subdirectories of a "home" directory
     (I use C:\USR\DAK).  Setting the HOME environment variable to this
     directory provides the easiest way of returning to your work area.

     The CDHISTFILE environment variable allows you to store the history
     in a location other than the root directory of the C drive, and to
     give the file a name of your choosing.  (By the way, you might've
     wondered why I chose "C:\CDHIST" and not just "\CDHIST" as the
     default name for the history file.  The answer is this: if I chose
     "\CDHIST", CDH would create a history file in the root directory of
     every drive you visited.  By choosing "C:\CDHIST", there is only one
     history file, regardless of the number of disk drives or partitions.)

     9                                                                   9


     By far the most powerful environment variable is CDPATH.  This
     provides an easy way to access subdirectories in a particular
     directory tree.  For example, you might prefer to install all your
     Windows applications in a subdirectory of the WINDOWS directory, for
     example, C:\WINDOWS\APPS.  By including this directory in the CDPATH,
     you can change to the application's directory by using its name only.
     If you use a "home" directory, you could include it in the CDPATH
     also.  Finally, the root directory is another candidate for CDPATH.
     Here is a command to set a typical CDPATH environment variable:

          set CDPATH=C:\WINDOWS\APPS;C:\USR\DAK;C:\

     With this command in effect, you could change to the Lotus 123 for
     Windows directory (for example, C:\WINDOWS\APPS\123W) by typing:
     CDH 123W.


     HARDWARE REQUIREMENTS
     ======================

     It is feasible to use CDH without a hard disk.  Realistically,
     however, a hard disk is the minimum requirement.  If you do not have
     a hard disk, or your hard disk is not drive C, you must use the
     CDHISTFILE environment variable to specify the name of the history
     file.

     There is no real advantage in placing CDH.EXE in a RAM drive.  It has
     to access the hard disk to read the history file anyway, so there is
     very little performance benefit.  Placing the history file in the RAM
     disk is also of little use, because you lose your directory history
     each time you boot your computer.


     DIAGNOSTICS
     ===========

     CDH returns exit code 0 if the argument is valid or the directory
     change is successful.  Otherwise it prints a diagnostic message and
     returns exit code 1.


     BUGS AND ENHANCEMENTS
     =====================

     As far as I can tell, CDH is bug-free.  However, I am always
     interested in hearing about people's experiences.  If you find a bug,
     or have an enhancement request, please tell me about it.  Write to:

          Dave Kruger
          PO Box 293
          Bentleigh, 3204
          Victoria, Australia

          Internet:  dak@hparc0.aus.hp.com

     10                                                                 10


     VERSION AND HISTORY
     ===================

     Version 5.0, the current version, is the first released version.
     Previous versions represented incremental implementation of the
     version 5.0 functionality, or bug fixes resulting from beta testing.
     The first fully working version was version 2.0, 20 March 1990.

     CDH was written in Turbo C by Dave Kruger.  It is based on a UNIX ksh
     script written by an unknown author, but modified by Alan Barnes and
     Tim Segall at Hewlett-Packard's Australian Software Operation.
