1wcd(1)                            2023-04-23                            wcd(1)
2
3
4

NAME

6       wcd - Wherever Change Directory
7
8       chdir for DOS and Unix
9

SYNOPSIS

11           wcd [options] [directory]
12

DESCRIPTION

14   Overview
15       Wcd is a command-line program to change directory fast. It saves time
16       typing at the keyboard. One needs to type only a part of a directory
17       name and wcd will jump to it. Wcd has a fast selection method in case
18       of multiple matches and allows aliasing and banning of directories. Wcd
19       also includes a full screen interactive directory tree browser with
20       speed search.
21
22       Wcd was modeled after Norton Change Directory (NCD). NCD appeared first
23       in The Norton Utilities, Release 4, for DOS in 1987, published by Peter
24       Norton.
25
26       Wcd has been ported to different command-line shells: DOS command.com,
27       Windows cmd.exe and PowerShell, OS/2 cmd.exe, and Unix shells such as
28       Bourne (sh), Bourne Again (bash), Korn (ksh), Z (zsh), and C (csh)
29       shell and others running on any operating system.
30
31       Wcd supports 8 bit character sets on all systems, and has optional
32       support for Unicode. See section LOCALIZATION.
33
34       See section INSTALLATION how to setup wcd for personal use.
35
36   Basic use
37       By default (if no wildcards are used) wcd searches for a directory with
38       a name that begins with the typed name.
39
40       For instance this command will change to directory to the current
41       user's "/home/user/Desktop":
42
43           wcd Desk
44
45       When there are multiple matches, wcd will present the user a list of
46       all matches. The user can then make a selection with a few keystrokes
47       (most of the times only one).
48
49   Wildcards
50       Wcd supports following wildcards:
51
52           *       matches any sequence of characters (zero or more)
53           ?       matches any character
54           [SET]   matches any character in the specified set,
55           [!SET]  or [^SET] matches any character not in the specified set.
56
57       A set is composed of characters or ranges; a range looks like character
58       hyphen character as in "0-9" or "A-Z". The "[0-9a-zA-Z_]" is the
59       minimal set of characters allowed in the "[..]" pattern construct.
60       International characters (i.e. 8 bit characters) are allowed if the
61       system supports them. To suppress the special syntactic significance of
62       any of "[]*?!^-\" inside or outside a "[..]" construct and match the
63       character exactly, precede the character with a backslash ("\") marker.
64
65       Using wildcards makes powerful searching possible. For instance this
66       matches any directory name that ends with "top":
67
68           wcd *top
69
70       Match directories that have "top" anywhere in the name:
71
72           wcd *top*
73
74       Match any directory name that begins with "a", "b" or "c":
75
76           wcd [a-c]*
77
78       It is also possible to give a part of a directory path. Here Wcd
79       searches for directory that begins with "Desk" and which path matches
80       *me/Desk*.
81
82           wcd me/Desk
83
84       It is allowed to type any kind of expression with slashes and
85       wildcards.  E.g.:
86
87           wcd src*/*1?/a*2
88
89   Other uses
90       If no wildcards are used and wcd finds a perfect match, wcd will ignore
91       all wild matches by default. This behaviour can be changed with the -w
92       option.
93
94       The interactive directory tree browser can be started by using option
95       -g.
96
97           wcd -g
98
99       Wcd generates a treedata file where it searches the directory. On Unix
100       and Windows systems wcd does add symbolic links to the treedata file
101       while scanning the disk, but does not follow them. While following
102       links wcd could end up scanning infinite loops, or scan very large
103       portions of a network.
104
105       Wcd can also change to directories that are not in the treedata file.
106       E.g.:
107
108           wcd ..
109
110       If wcd found a match but can't change to the directory it tries to
111       remove it from the default treedata file. Not from the extra treedata
112       file. See also option -k.
113
114       Wcd keeps a directory stack which is stored on disk. The stack has a
115       default size of 10 and is cyclic. See options -z, -, + and =.
116
117       In multi-user environments option -u can be used to change to
118       directories of other users.
119
120       On DOS and Windows systems it does not matter if you use a slash "/" or
121       a backslash "\" as a directory separator.
122
123       It is possible on DOS and Windows systems to change drive and directory
124       in one go by preceding the directory name with the drive name.
125
126           wcd d:games
127
128   Windows UNC paths
129       The Windows versions (Command Prompt, PowerShell, MSYS, zsh, cygwin)
130       support Windows SMB LAN UNC paths without drive letter such as
131       "\\servername\sharename". Wcd for Windows Command Prompt makes use of
132       the "pushd" command to automatically map a UNC path to a drive letter.
133       In Windows PowerShell, MSYS, zsh and Cygwin UNC paths are fully
134       supported. The current working directory can be a UNC path.
135
136   Console resizing on Windows
137       Wcd supports console resizing in Windows 10 console and ConEmu (see
138       <https://conemu.github.io/>) since version 6.0.3. The Windows 10
139       console must not be in legacy mode (check the console's properties).
140       The screen may not refresh when the console Layout property "Wrap text
141       output on resize" is disabled. The screen can be refreshed manually by
142       pressing the F5 key.
143
144   Interfaces
145       Wcd has three different interfaces to choose from a list of matches.
146       The interface can be chosen at compile time.
147
148       The first interface uses plain stdin/stdout. A numbered list is printed
149       in the terminal. The user has to choose from the list by typing a
150       number followed by <Enter>. This interface does not provide scroll back
151       functionality in case of a long list. The scroll back capability of the
152       terminal/console has to be used. It is very small and portable.
153
154       The second interface is built with the conio library. It provides a
155       builtin scroll back capability. The user is presented a list numbered
156       with letters.  Choosing from a list can be done by pressing just one
157       letter. This interface is fast because it saves keystrokes. If possible
158       the screen will be restored after exiting. One who prefers to type
159       numbers can use the -N option.
160
161       The third interface is built with the curses library. It is similar to
162       the conio interface. The curses version of wcd has also an additional
163       'graphical' interface. It lets the user select a directory via a full
164       screen interactive directory tree browser. It has a vim(1) like
165       navigation and search method. It can be activated with option -g.
166
167       By using the -o option one can always fall back to the stdin/stdout
168       interface.
169

OPTIONS

171       -a  Add current path to the default treedata file.
172
173           Use this option to quickly add the current path to the default
174           treedata file. Re-scanning the complete disk can take a long time
175           in some cases.
176
177       -aa Add current and all parent paths to the default treedata file.
178
179       -A PATH
180           Scan directory tree from PATH and append to the default treedata
181           file. Examples:
182
183               wcd -A .
184               wcd -A /home -A /etc
185               wcd -A d: -A e: -A \\server\share
186
187           On Windows one can scan all shared directories of a Windows LAN
188           server by typing something like: "wcd -A \\servername".
189
190           See also option -S and -s and -E.
191
192       -b  Ban current path.
193
194           Wcd places the current path in the ban file. This means that wcd
195           ignores all matches of this directory and its sub directories.
196
197           The ban file can be edited with a text editor. Use of wildcards is
198           supported and names are matched against the absolute path.
199
200           Banned paths are not excluded from scanning the disk. To do that
201           use option -xf.
202
203       -c, --direct-cd
204           Direct CD mode. By default wcd works as follows:
205
206               1. Try to find a match in the treedata file(s)
207               2. If no match, try to open the directory you typed.
208
209           In direct CD mode wcd works in reversed order.
210
211               1. Try to open the directory you typed.
212               2. If not, try to find a match in the treedata file(s).
213
214       -d DRIVE
215           Set drive for stack and go file (DOS only).
216
217           The stack file and the go-script are by default stored on drive C:
218           if environment variable HOME is not set. Use this option if drive
219           C: is a read-only drive. This option must be used in front of the
220           stack options -, + and =.
221
222       -e  Add current path to the extra treedata file.
223
224           Use this option to quickly add the current path to the extra
225           treedata file.
226
227       -ee Add current and all parent paths to extra treedata file.
228
229       -E PATH
230           Scan directory tree from PATH and append to Extra treedata file.
231           See also options -A and -S.
232
233       -f FILE
234           Read treedata file FILE. Do not read the default treedata file.
235
236       +f FILE
237           Read treedata file FILE in addition to the default treedata file.
238
239       -g  Graphical interface (only in version with curses interface).
240
241           Wcd starts a textual curses based 'graphical' interface. The user
242           can select a directory via a full-screen interactive directory tree
243           browser. It has a vim(1) like navigation and search method.
244
245           If no search string is given wcd presents the whole tree which is
246           in the default treedata file and the extra treedata files.
247
248           If a search string is given the match list is presented as a
249           directory tree.
250
251           The default tree layout is similar to the tree layout of the
252           original NCD on DOS. The difference in layout is that in NCD all
253           directories of a same depth level were vertically aligned over the
254           whole tree. This was possible in NCD, because the maximum width of
255           a directory name in DOS was 12 (8.3) characters. On modern
256           operating systems directory names can be very long, so also the
257           differences in length can be large. Therefore folders with a same
258           depth are not vertically aligned over the whole tree in wcd, but
259           only in sub-branches.  So there is some sideways movement when
260           moving straight up and down from one sub-branch to another sub-
261           branch.
262
263           The navigation behaviour in Wcd is exactly the same as in the
264           original NCD. For instance if you push the Down key you go down to
265           the next directory with the same depth level, jumping over
266           branches. This enables fast navigation through the tree.
267
268           See options -Ta, -TC, and -Tc to change the navigation behaviour.
269
270       -gd Dump the treedata files as a tree to stdout.
271
272       -G PATH
273           Write go-script in directory PATH. For instance on Unix, "wcd -G
274           PATH" will write a go-script PATH/wcd.go.
275
276       -GN, --no-go-script
277           Do not create go-script. This option can be used in combination
278           with the option -j if one does not want wcd to create a go-script.
279
280       -h, --help
281           Show help and exit.
282
283       -i, --ignore-case
284           Ignore case.  Dos and Windows versions of wcd ignore case default.
285           Unix/Cygwin versions regard case by default.
286
287       +i, --no-ignore-case
288           Regard case. See also option -i.
289
290       -I, --ignore-diacritics
291           Ignore diacritics for Latin-based scripts.  Letters with
292           diacritical marks match their base letter without diacritical mark.
293           The following Latin encodings are supported: CP437, CP850, CP852,
294           CP1250, CP1252, ISO-8859-1, ISO-8859-2, and Unicode Latin-1, Latin
295           Extended-A, and Latin Extended-B.  See also
296           <http://en.wikipedia.org/wiki/Diacritic>
297
298       +I, --no-ignore-diacritics
299           Regard diacritics (default). See also option -I.
300
301       -j, --just-go
302           Just go mode.
303
304           In this mode wcd will not present a list when there is more than
305           one directory that matches the given directory. Wcd will just
306           change to the first option. When wcd is invoked again with the same
307           arguments it will change to the next option, and so on.
308
309           Wcd will print the directory to go to to stdout. So a different
310           installation method can be used. One could make the following
311           function for a POSIX compatible shell:
312
313               wcd ()
314               {
315                   cd "$($HOME/bin/wcd.exe -j $@)"
316               }
317
318           When you are using an old shell that doesn't support "$()" command
319           substitution you have to use old style command substitution with
320           back-quotes.
321
322               wcd ()
323               {
324                   cd "`$HOME/bin/wcd.exe -j $@`"
325               }
326
327           On Windows systems, if one is running 4NT shell, one could make the
328           following alias:
329
330               alias wcd `cd %@execstr[wcdwin32.exe -z 0 -j %1]`
331
332           This method eliminates the need of the go-script, so one can use
333           option -GN in combination with -j.
334
335       -k, --keep-paths
336           Keep paths.
337
338           Keep paths in the treedata file when wcd can't change to them. The
339           default behaviour of wcd is that it tries to remove paths from the
340           treedata when wcd can't change to them. With this option this
341           behavior is turned off.
342
343       -K, --color
344           Use colors in graphical mode.
345
346       -l ALIAS
347           Name the current path with ALIAS. Wcd places the current path with
348           alias ALIAS in the alias file. Aliases are case sensitive.
349
350       -ls Show the name of the alias file, and list all the aliases.
351
352       -m DIR
353           Make directory and add to treedata file.
354
355       -L, --license
356           Print the distribution license.
357
358       -M DIR
359           Make directory and add to extra treedata file.
360
361       -n PATH
362           Read relative treedata file from PATH.
363
364           Do not read the default treedata file. The relative treedata file
365           should already have been created using the wcd +S option.  PATH may
366           also point to a file directly.
367
368           An example. Suppose another system has been mounted to mount point
369           "/mnt/network":
370
371               wcd -n /mnt/network src
372
373           Wcd opens the relative treedata file in "/mnt/network/". The file
374           contains the paths relative from that point.
375
376       +n PATH
377           Read relative treedata file in addition to the default treedata
378           file. See option -n.
379
380       -N, --numbers
381           Use numbers instead of letters.
382
383           Wcd with a conio or curses based interface (see section Interfaces)
384           presents a match list by default numbered with letters. When the -N
385           option is used the match list is numbered with numbers. Regardless
386           of the -N option one can type a letter or numbers to make a
387           selection from the list of matches.
388
389       -o  Use stdin/stdout interface.
390
391           When for some kind of reason the conio or curses interface of wcd
392           does not work one can fall back to the stdin/stdout interface of
393           wcd by using the -o option.
394
395       -od, --to-stdout
396           Dump all matches to stdout.
397
398       -q, --quiet
399           Quieter operation. Printing of the final match is suppressed.
400
401       -r DIR
402           Remove directory and remove from the treedata file.
403
404           If the directory is empty, wcd will remove it, and try to remove it
405           from the treedata file.
406
407       -rmtree DIR
408           Recursively remove directory and remove from the treedata file.
409
410           Wcd will remove the directory and all its sub directories and
411           files, and remove the directories from the treedata file.
412
413       -s  (re)Scan disk from $HOME directory. If HOME is not defined the disk
414           is scanned from root directory /.
415
416           The existing default treedata file is overwritten.
417
418           The default scan directory can be overruled with environment
419           variable "WCDSCAN". See section ENVIRONMENT VARIABLES.
420
421       -S PATH
422           Scan directory tree from PATH and overwrite the default treedata
423           file.  See also options -A, -s and -E. E.g. with option -A you can
424           create a default treedata file of your choice. Examples:
425
426           Unix:
427
428               wcd -S /
429               wcd -S /home -A /etc -A /usr
430
431           DOS/Windows:
432
433               wcd -S c:/
434               wcd -S c: -A d: -A \\server\share
435
436           With the Windows versions one can scan all shared directories of a
437           Windows LAN server by typing something like: "wcd -S \\servername".
438
439       +S PATH
440           Scan disk from PATH and place relative paths in a relative treedata
441           file.  This file is used by the -n and +n options of wcd. E.g. "wcd
442           -n PATH src".
443
444       -t  Do not strip tmp mount dir "/tmp_mnt" (Unix only)
445
446           Wcd strips by default "/tmp_mnt/" from the match. Directory
447           "/tmp_mnt" is used by the auto-mounter. This behaviour can be
448           turned off with the -t option.
449
450       -T, --ascii-tree
451           Draw tree with ASCII characters. Use this option if line drawing
452           characters are not displayed properly in your terminal.
453
454       -Ta, --alt-tree-nav
455           Alternative way of navigation in the graphical tree.
456
457           In the default NCD style tree layout the -Ta option disables
458           jumping to unrelated directories.
459
460           In compact tree mode the alternative mode makes navigation similar
461           to navigation in GUI file managers such as Windows Explorer or
462           Linux KDE Konqueror. Pressing Up and Down moves the selected folder
463           one line up or down. Pressing Left first folds the sub-folders and
464           the next move left moves really left.
465
466           You can switch on-the-fly between default and alternative
467           navigation by pressing <Shift-A>.
468
469           When alternative navigation mode is on, you will see an "A" in the
470           lower right corner.
471
472       -TC, --center-tree
473           Centered view in the graphical tree. The selected directory stays
474           in the middle of the screen. The centered mode can also be switched
475           on and off with key <t> in the graphical tree.
476
477           The standard non-centered behaviour, which minimises tree movement,
478           is the same as in the original NCD.
479
480       -Tc, --compact-tree
481           By default the 'graphical' tree is drawn the same way as the
482           original NCD on DOS did it. On DOS a directory path could only be
483           66 characters in total. With the deep directory structures of today
484           the tree can become very wide. To overcome this wcd can draw the
485           tree in a compact way, similar to most GUI file managers, with only
486           one folder per line. Use option -Tc or switch on-the-fly with the
487           <m> key.
488
489       -Td, --cjk-width
490           Legacy East-Asian CJK (Chinese, Japanese, and Korean) fonts have
491           certain characters and line drawing symbols with a column width of
492           2, while the normal Unicode width for these characters is 1 column.
493           For instance the Chinese CP936 raster font on Windows and the
494           Simsun font. Use this option for a correct outlining of the
495           graphical tree when a legacy CJK font is used.
496
497           When CJK mode is on, you will see a "C" in the lower right corner.
498
499       -u USER
500           Scan treedata file of another user based on USER, do not scan your
501           own default treedata file. See also section ENVIRONMENT VARIABLES
502           for WCDUSERSHOME.
503
504           On Unix/Cygwin the base directory for user home directories is
505           assumed to be "/home". Wcd will look for "/home/USER/.treedata.wcd"
506           and "/home/USER/.wcd/.treedata.wcd", in that order, and read the
507           first one that exists and is readable.  On DOS/Windows the base
508           directory for user home directories is assumed to be "\\users", so
509           wcd tries to read "\\users\USER\treedata.wcd" and
510           "\\users\USER\.wcd\treedata.wcd".
511
512       +u USER
513           Read default treedata file of USER in addition to your own treedata
514           file.
515
516       -v, --verbose
517           Display verbose messages. With this option wcd prints all filters,
518           bans and excludes.
519
520       -V, --version
521           Print version information and exit.
522
523       -w, --wild-match-only
524           Wild matching only. Treat all matches as wild matches.
525
526       -x PATH
527           Exclude PATH from scanning.
528
529           When this option is used wcd will exclude PATH and all its
530           subdirectories when wcd is scanning a disk. Wildcards are supported
531           and matched against absolute paths. Option -x can be used multiple
532           times.
533
534               wcd -x <path1> -x <path2> -s
535
536           Option -x must be used in front of any scan option (-s, -S, +S, -A,
537           -E).
538
539           On DOS/Windows systems one must specify the drive letter depending
540           on if environment variable HOME or WCDHOME is set. If HOME or
541           WCDHOME is set one needs to specify the drive letter. An example:
542
543               wcd -x c:/temp -S c:
544
545           Otherwise do not specify drive letter.
546
547               wcd -x /temp -s
548
549       -xf FILE
550           Exclude all paths listed in FILE from scanning.
551
552           When this option is used wcd will exclude all paths listed in FILE
553           and all their subdirectories when wcd is scanning a disk. Wildcards
554           are supported and they are matched against absolute paths; one path
555           per line. Be aware that wcd will not ignore leading or trailing
556           blanks on a line, because they are legal characters in a directory
557           name. Option -xf can be used multiple times. When one wants to
558           exclude all banned paths from scanning one can do the following
559           (example for wcd on unix):
560
561               wcd -xf ~/.ban.wcd -s
562
563           Wildcards are supported. For instance to exclude all your
564           Subversion directories with administrative files add a line with
565           "*/.svn".
566
567           Option -xf must be used in front of any scan option (-s, -S, +S,
568           -A, -E).
569
570       -y, --assume-yes
571           Assume Yes on all queries.
572
573           Wcd will not prompt the user with yes/no questions, but assumes the
574           user answers yes on all questions. This can be used in combination
575           with option -rmtree. This option must be used in front of options
576           that can lead to yes/no questions.
577
578       -z NUMBER
579           Set maximum stack size to NUMBER.
580
581           The default size of the stack is 10. Stack operation can be turned
582           off by setting the size to 0. This option must be used in front of
583           any other stack operations (-,+,=). Otherwise the size of the stack
584           will be set back to the default 10.
585
586           A correct command is:
587
588               wcd -z 50 -
589
590           The new stack size will be 50, wcd will go one directory back. A
591           wrong command is:
592
593               wcd - -z 50
594
595           Wcd goes one directory back, the stack gets the default size 10.
596           The -z 50 is ignored.
597
598           Add this option as the first option to your wcd alias or function.
599           E.g.  for the a POSIX compatible shell this would be:
600
601               wcd ()
602               {
603                   wcd.exe -z 50 "$@"
604                   . ${WCDHOME:-${HOME}}/bin/wcd.go
605               }
606
607       -[NUMBER]
608           Push dir NUMBER of times. Default is one.
609
610           Go back a directory. Command "wcd -" goes one directory back. To go
611           more directories back add a number to it. E.g. command "wcd -3".
612           The stack is cyclic.
613
614       +[NUMBER]
615           Pop dir NUMBER of times. Default is one.
616
617           Go forward a directory. Command "wcd +" goes one directory forward.
618           To go more directories forward add a number to it. E.g. command
619           "wcd +2". The stack is cyclic.
620
621       =   Show stack.
622
623           Use this option if you do not know anymore how many times to push
624           or pop.  The stack is printed and you can choose a number. The
625           current place in the stack is marked with an asterisk "*".
626

INSTALLATION

628       The current working directory of a Unix shell can only be changed by
629       the builtin cd(1) command. Therefore the program is always called by a
630       function or an alias. The function or alias sources a shell script (go-
631       script) which is generated by the wcd program. Wcd can only work after
632       the function or alias is defined.
633
634       Another important influence on your installation is the definition of
635       environment variables HOME and WCDHOME. See section ENVIRONMENT
636       VARIABLES.
637
638   Install for POSIX type shells
639       For a POSIX shell (ksh, bash, zsh, etc.) on Unix, Linux, Cygwin, or
640       native MSYS add the following function to the shell startup file (e.g.
641       Bash uses "$HOME/.bashrc"):
642
643           wcd ()
644           {
645               PATH/wcd.exe "$@"
646               . ${WCDHOME:-${HOME}}/bin/wcd.go
647           }
648
649       Replace PATH with the location where the wcd executable has been
650       installed. Reload the shell initialization files or start new shell.
651
652       The location of the go-script "wcd.go" differs per shell.
653
654       Wcd for DJGPP DOS bash and OS/2 bash require a different function. The
655       go script is not written in a directory "bin", and if WCDHOME and HOME
656       are both not defined the go-script is written on c:/.
657
658       DOS bash:
659
660           wcd ()
661           {
662               PATH/wcdbash.exe "$@"
663               . ${WCDHOME:-${HOME:-"c:"}}/wcd.go
664           }
665
666       OS/2 bash:
667
668           wcd ()
669           {
670               PATH/wcdos2bash.exe "$@"
671               . ${WCDHOME:-${HOME:-"c:"}}/wcd.go
672           }
673
674       The WinZsh version of wcd requires a bit different function. The go-
675       script will never be written in c:/.
676
677           wcd ()
678           {
679               PATH/wcdwin32zsh.exe "$@"
680               . ${WCDHOME:-${HOME}}/wcd.go
681           }
682
683       See section FILES for more information.
684
685   Install for C-alike shells (csh, tcsh)
686       Add the following alias to the shell startup file "$HOME/.cshrc" or
687       "$HOME/.tcshrc" :
688
689           if ( ${?WCDHOME} ) then
690               alias wcd "PATH/wcd.exe \!* ; source $WCDHOME/bin/wcd.go"
691           else
692               alias wcd "PATH/wcd.exe \!* ; source $HOME/bin/wcd.go"
693           endif
694
695       Replace PATH with the location where the wcd executable has been
696       installed.  Reload the shell initialization files or start a new shell.
697
698   Windows Command Prompt version
699       Unpack the zip file and add directory "bin" to your environment
700       variable PATH.
701
702       In Windows Command Prompt a Windows program cannot change the current
703       work directory, but a .bat file can. The batch script "wcd.bat" runs
704       the wcd program which generates a new batch script "wcdgo.bat". Then
705       "wcd.bat" runs "wcdgo.bat" which actually changes the directory.
706
707   Windows VISTA and higher
708       In a Windows VISTA and higher Command Prompt you may have limited
709       access to directories. To get access to more directories you need
710       administrator rights. You can get a Command Prompt with administrator
711       rights if you right click on the Command Prompt icon and select Run as
712       administrator.
713
714   Windows PowerShell version
715       Add the following function to your PowerShell user profile. The
716       location of this profile is stored in the $profile variable. It is
717       required that one of the environment variables HOME or WCDHOME is
718       defined.
719
720           function wcd
721           {
722               PATH\wcdwin32psh.exe $args
723               & $env:HOME\wcdgo.ps1
724           }
725
726       Replace PATH with the location where the wcd executable has been
727       installed.  Start a new PowerShell. Wcd for PowerShell supports only
728       the file system provider. No other providers.
729
730   OS/2 Command Prompt version
731       In an OS/2 Command Prompt (cmd.exe) an OS/2-program can't change the
732       current work directory. That is why wcd generates a command script
733       "wcdgo.cmd" which must be executed in the current shell. The script
734       "wcd.cmd" first executes "wcdos2.exe", which creates the "wcdgo.cmd"
735       script. Then "wcd.cmd" executes the "wcdgo.cmd" script.
736

LOCALIZATION

738       LANG
739           The primary language is selected with the environment variable
740           LANG. The LANG variable consists out of several parts. The first
741           part is in small letters the language code. The second one is
742           optional and is the country code in capital letters, preceded with
743           an underscore. There is also an optional third part: character
744           encoding, preceded with a dot. A few examples for POSIX standard
745           type shells:
746
747               export LANG=nl               Dutch
748               export LANG=nl_NL            Dutch, The Netherlands
749               export LANG=nl_BE            Dutch, Belgium
750               export LANG=es_ES            Spanish, Spain
751               export LANG=es_MX            Spanish, Mexico
752               export LANG=en_US.iso88591   English, USA, Latin-1 encoding
753
754           For a complete list of language and country codes see the
755           gettext(1) manual:
756           <http://www.gnu.org/software/gettext/manual/gettext.html#Language-Codes>
757           On Unix systems you can use to command locale(1) to get locale
758           specific information.
759
760       LANGUAGE
761           With the LANGUAGE environment variable you can specify a priority
762           list of languages, separated by colons. Wcd gives preference to
763           LANGUAGE over LANG. For instance, first Dutch and then German:
764           "LANGUAGE=nl:de". You have to first enable localization, by setting
765           LANG or LC_ALL to a value other than C, before you can use a
766           language priority list through the LANGUAGE variable. See also the
767           gettext(1) manual:
768           <http://www.gnu.org/software/gettext/manual/gettext.html#The-LANGUAGE-variable>
769
770           If you select a language which is not available you will get the
771           standard English messages.
772
773       WCDLOCALEDIR
774           With the environment variable WCDLOCALEDIR the LOCALEDIR used
775           during compilation and installation of wcd can be overruled.
776           LOCALEDIR is used by wcd with native language support to find the
777           language files. The GNU default value is "/usr/local/share/locale".
778           By typing "wcd -V" wcd will print the LOCALEDIR that is used.
779
780           If you have installed wcd in a different directory than the default
781           directory you may need to set the environment variable WCDLOCALEDIR
782           to point to the locale directory.
783
784           An example for Windows cmd:
785
786               set WCDLOCALEDIR=c:/my_prefix/share/locale
787
788           An example for a POSIX shell:
789
790               export WCDLOCALEDIR=$HOME/share/locale
791
792       LC_COLLATE
793           When there are multiple directory matches wcd presents a sorted
794           list. The sorting depends on the locale settings. If the
795           environment LANG has been set the matches are sorted like
796           dictionaries or phone books are sorted in that language. For
797           instance dots and dashes are ignored, or letters e with and without
798           accent are equal, or upper and lower case is ignored.
799
800           The sorting gives preference to environment variable LC_COLLATE
801           over LANG. If you make LC_COLLATE equal to "C" or "POSIX", locale
802           sorting is turned off. For instance if you want Dutch language, but
803           not Dutch sorting, you can do something like this:
804
805               export LANG=nl_NL
806               export LC_COLLATE=C
807
808       LC_CTYPE
809           With regard to character encoding Wcd will give preference to
810           variable LC_CTYPE over LANG. For instance to set character encoding
811           to UTF-8 the following environment setting can be done.
812
813               export LC_CTYPE=en_US.UTF-8
814
815       LC_ALL
816           All locale environment variables that start with LC_ are overruled
817           by the environment variable LC_ALL if it is defined. Wcd gives
818           preference to LC_ALL over LC_COLLATE and LC_CTYPE.
819
820   WINDOWS CODE PAGES
821       There are two groups of code pages: DOS code pages (OEM) and Windows
822       code pages (ANSI). The default encoding for Windows, when configured
823       with Western regional settings, is ANSI CP1252. Windows programs, for
824       instance notepad, use this default system ANSI code page. The Windows
825       console uses by default an OEM code page (CP437 or CP850) for
826       compatibility with DOS programs. If you use a DOS version of wcd in a
827       Windows console it will work, because of the DOS code page.  But the
828       DOS version of wcd lacks support for long directory names and network
829       drives on Windows.
830
831       The Windows version of wcd is a native Windows program and will use the
832       Windows system ANSI code page. So on a Western regional Windows it will
833       use code page CP1252 for directory names and messages. In order to get
834       consistent output, independent of the active code page, all Windows
835       versions of Wcd translate ANSI output to Unicode output in the Command
836       Prompt and PowerShell.
837
838       The console raster font only supports the original OEM code page
839       installed with Windows, so you have to change the console's font to
840       true type Lucida Console to make Unicode (and ANSI) letters appear
841       correctly.
842
843       Non-Unicode versions of Wcd prior to version 5.2.0 use plain ANSI
844       output.  For these older versions the code page of the console has to
845       be made equal to the system code page (changed to 1252) to make wcd for
846       Windows work properly with special characters such as accented
847       characters or the Euro symbol.
848
849       The Windows system code page can be changed via the Control Panel
850       regional options. The Windows console code page is changed with the
851       "chcp" command.
852
853       When you type "wcd -V", the actual character encoding used by wcd is
854       shown. Type the command "chcp" to display the active code page of the
855       Windows console.
856
857   UNICODE
858       Wcd has optional support for Unicode. To see if wcd was built with
859       Unicode support type "wcd -V". If your terminal/console and font
860       supports it, you should see the Euro symbol and Chinese characters
861       (meaning: "Chinese").
862
863       Wcd has been soft converted to Unicode. In its core wcd handles all
864       data as a stream of bytes. Only the lines printed to screen are on the
865       fly converted to Unicode wide characters. Wcd fully relies on libc
866       functions and has no UTF-8 specific code. See also
867       <http://www.cl.cam.ac.uk/~mgk25/unicode.html>
868
869       Wcd has optional support for Unicode matching with normalisation. To
870       find out whether Wcd has normalisation support type "wcd -V".  Wcd with
871       Unicode normalization support will match Unicode names based on
872       compatible equivalence. Without Unicode normalization support, names
873       are matched when they are binary equivalent.  See also
874       <http://en.wikipedia.org/wiki/Unicode_normalization>
875
876       UTF-8 on Unix/Linux
877
878       In order to view UTF-8 characters your console/terminal also needs to
879       support UTF-8. The xterm version that comes with XFree86 4.0 or higher
880       includes UTF-8 support. To activate it, start xterm(1) in a UTF-8
881       locale and use a font with iso10646-1 encoding, for instance with
882
883           LC_CTYPE=en_GB.UTF-8 xterm -u8 -fn '-Misc-Fixed-Medium-R-SemiCondensed--13-120-75-75-C-60-ISO10646-1'
884
885       Modern distributions of GNU/Linux support UTF-8 by default. Other
886       multi-byte character encodings should also work, but that has not been
887       tested.
888
889       Wcd assumes that the treedata files are encoded in the locale character
890       encoding. There are no Byte Order Marks written to treedata files.
891
892       UTF-16 on Windows
893
894       On Windows Unicode is supported in all versions of PowerShell, and in
895       Windows Command Prompt on Windows 7 (or higher). Unicode also works in
896       Take Command or TCC/LE made by JP Software, which can be used on older
897       Windows versions (XP/Vista).
898
899       On Windows all the directory names on disk are encoded in UTF-16
900       Unicode.  For non-Unicode Windows programs the Unicode characters are
901       translated to the default ANSI code page. For characters that are not
902       part of the regional setting this translation is not possible and non-
903       Unicode programs print a question mark or a wrong character instead.
904
905       Wcd with Unicode support will read the UTF-16 encoded directory names
906       and converts them internally to UTF-8. All treedata files are encoded
907       in UTF-8 and not compatible with the non-Unicode version of Wcd. Wcd
908       will create a go-script encoded in UTF-8.
909
910       All versions of Windows PowerShell are able to run scripts encoded in
911       UTF-8, provided there is an UTF-8 BOM in the script.
912
913       Since Windows 7 it is possible in Windows Command Prompt to change
914       directory with a batch script to a directory with Unicode letters in
915       the name. The directory name needs to be encoded in UTF-8, and the
916       batch script must not have a BOM. The active code page of the Command
917       Prompt needs to be set to 65001 (UTF-8) prior to the cd command. Wcd
918       for Command Prompt will create such a go script "wcdgo.bat". It first
919       changes the code page to 65001, then changes directory, and finally
920       sets the code page back to the original code page.
921
922       You need to set the font to True Type Lucida Console (not raster font)
923       when letters don't appear correctly.
924
925       The non-Unicode Windows version of Wcd can read Unicode treedata files
926       since version 5.2.0, provided there is a Byte Order Mark (BOM) in the
927       file (see <http://en.wikipedia.org/wiki/Byte_order_mark>), but it can't
928       change to directories with Unicode letters in the name that are not
929       part of the default system ANSI code page. The Unicode Windows version
930       of wcd writes a BOM in the UTF-8 encoded treedata files since version
931       5.2.0, which makes them also readable by notepad.
932
933       UTF-8 on Cygwin
934
935       Cygwin supports Unicode since version 1.7. The Cygwin layer takes care
936       that the Windows UTF-16 Unicode names are converted to UTF-8. So
937       programs, like wcd, do not need to be aware of this and can operate
938       using UTF-8 encoding as on Unix/Linux. Set character encoding to UTF-8
939       with the LANG or LC_CTYPE environment variable. You may need to rescan
940       your drives. You need to set the font to True Type Lucida Console (not
941       raster font) if you use the default Cygwin console.
942
943       The Cygwin version behaves exactly as the Unix version of wcd.  There
944       is no BOM written in the treedata files, and it is assumed they are
945       encoded in the Cygwin locale character encoding.
946

FILES

948       If the environment variable WCDHOME is set wcd will use WCDHOME instead
949       of HOME. All "*.wcd" files are text files. They can be edited with a
950       text editor.  The Windows Command Prompt version of wcd behaves as the
951       DOS version. The Cygwin version of wcd behaves as the Unix version.
952
953       wcd.exe
954           The program. In Unix shells the program is always called by a
955           function or alias, because the current working directory of a Unix
956           shell can only be changed by the builtin cd command. See also
957           section INSTALLATION.
958
959       default treedata file
960           This is the default treedata file where wcd searches for matches.
961           If it is not readable wcd will create a new one.
962
963               DOS: \treedata.wcd or %HOME%\treedata.wcd
964               Unix: $HOME/.treedata.wcd
965
966       extra treedata file
967           An optional extra treedata file. If it exists and is readable wcd
968           will try to find matches in this file also.
969
970               DOS: \extra.wcd or %HOME%\extra.wcd
971               Unix: $HOME/.extra.wcd
972
973       ban file
974           In this optional file wcd places banned paths. See option -b.
975           Wildcards are supported.
976
977               DOS: \ban.wcd or %HOME%\ban.wcd
978               Unix: $HOME/.ban.wcd
979
980       alias file
981           Optional file with wcd aliases. See option -l.
982
983               DOS: \alias.wcd or %HOME%\alias.wcd
984               Unix: $HOME/.alias.wcd
985
986       stack file
987           In this file wcd stores its stack. The drive letter can be changed
988           with the -d option.
989
990               DOS: c:\stack.wcd or %HOME%\stack.wcd
991               Unix: $HOME/.stack.wcd
992
993           The name of the stack file can be changed with environment variable
994           WCDSTACKFILE.  See section ENVIRONMENT VARIABLES.
995
996       go-script
997           This is the shell script which wcd.exe creates each time. It is
998           sourced via a function or an alias. The drive letter can be changed
999           with the -d option.  For history reasons it is placed by default in
1000           "$HOME/bin" on Unix systems. The directory of this file can be
1001           changed with the option -G.
1002
1003               DOS bash: c:/wcd.go or $HOME/wcd.go
1004               Windows Command Prompt: c:\wcdgo.bat or %HOME%\wcdgo.bat
1005               Windows PowerShell: $env:HOME\wcdgo.ps1
1006               WinZsh: $HOME/wcd.go
1007               Cygwin/MSYS: $HOME/bin/wcd.go
1008               OS/2 Command Prompt: c:\wcdgo.cmd or %HOME%\wcdgo.cmd
1009               OS/2 bash: c:/wcd.go or $HOME/wcd.go
1010               Unix: $HOME/bin/wcd.go
1011
1012       relative treedata file
1013           Text file with relative paths from DIR. See options +S, -n and +n.
1014
1015               DOS: PATH\rtdata.wcd
1016               Unix: PATH/.rtdata.wcd
1017

ENVIRONMENT VARIABLES

1019       HOME
1020           Wcd uses by default environment variable HOME to determine where to
1021           store its files. See also section FILES. This can be overruled with
1022           environment variable WCDHOME.
1023
1024           HOME also defines where to start scanning the disk when option -s
1025           is used. This can be overruled with the environment variable
1026           WCDSCAN.
1027
1028           For the Unix, Cygwin, Windows PowerShell, WinZsh and MSYS version
1029           it is required that HOME or WCDHOME is set. For the other versions
1030           of wcd the use of these variables is optional.
1031
1032           If HOME is set on DOS/Windows, wcd will place all its files
1033           (treedata.wcd, extra.wcd, alias.wcd, ban.wcd, wcd.go) in directory
1034           HOME. The behaviour of wcd is then equal to the Unix version of
1035           wcd. Wcd will scan the disk default from HOME. Drives will not be
1036           automatically scanned by changing to them. You need to tell wcd
1037           explicitly. E.g.:
1038
1039               wcd -S c: -A d: -A e:
1040
1041           Matching of directories is now global over all scanned drives.
1042
1043       WCDHOME
1044           Environment variable WCDHOME can be used to change the location of
1045           wcd's files. If both HOME and WCDHOME are set, WCDHOME will be used
1046           instead of HOME.
1047
1048           In wcd versions prior to 5.1.5 WCDHOME also changed the default
1049           scan directory.  This has changed. Since version 5.1.5 WCDHOME does
1050           not change the default scan directory. See option -s. From version
1051           5.1.5, use environment WCDSCAN to overrule the default scan
1052           directory.
1053
1054           Example for DOS, Windows, OS/2 Command Prompt:
1055
1056               set WCDHOME=C:\Users\erwin\wcd
1057
1058           An example for POSIX type shells:
1059
1060               export WCDHOME="$HOME/.wcd"
1061
1062           An example for Csh type shells:
1063
1064               setenv WCDHOME "$HOME/.wcd"
1065
1066       WCDSCAN
1067           Use environment variable WCDSCAN to overrule the default scan
1068           directory HOME. Define a colon separated list (Unix) to define more
1069           than one directory.  On DOS/Windows make the list semi-colon
1070           separated.
1071
1072           Examples for DOS, Windows, OS/2 Command Prompt:
1073
1074               set WCDSCAN=C:\Users\erwin;D:\data
1075
1076               set WCDSCAN=%HOMEDRIVE%%HOMEPATH%;\\projectdrive\projectX
1077
1078           An example for POSIX type shells:
1079
1080               export WCDSCAN="$HOME:/projectdisk/projectX"
1081
1082           An example for Csh type shells:
1083
1084               setenv WCDSCAN "$HOME:/projectdisk/projectX"
1085
1086       WCDFILTER
1087           Specify filters with environment variable WCDFILTER. All
1088           directories that do not match the filter(s) are ignored. A list can
1089           be specified by separating filters by the shell path separator.
1090           Similar as specifying the PATH variable.  The case sensitivity is
1091           mandated by the Operating system.
1092
1093           An example for DOS, Windows, OS/2 Command Prompt:
1094
1095               set WCDFILTER=projects;doc
1096
1097           An example for POSIX type shells:
1098
1099               export WCDFILTER="projects:doc"
1100
1101           An example for Csh type shells:
1102
1103               setenv WCDFILTER "projects:doc"
1104
1105       WCDBAN
1106           The paths specified with environment WCDBAN will be banned by wcd.
1107           See also option -b. Specify a list of paths separated by shell PATH
1108           separator.
1109
1110       WCDEXCLUDE
1111           The paths specified with environment WCDEXCLUDE will be excluded by
1112           wcd. See also options -x and -xf. Specify a list of paths separated
1113           by shell PATH separator.
1114
1115           An example for DOS, Windows, OS/2 Command Prompt:
1116
1117               set WCDEXCLUDE=*/windows;*/temp;*CVS
1118
1119           An example for POSIX type shells:
1120
1121               export WCDEXCLUDE="/dev:/tmp:*CVS"
1122
1123           An example for Csh type shells:
1124
1125               setenv WCDEXCLUDE "/dev:/tmp:*CVS"
1126
1127       WCDUSERSHOME
1128           Set the base of user's home directories.  On DOS/Windows the
1129           default value is "\\users".  On Unix/Cygwin the default value is
1130           "/home".  This variable is used to scan treedata files of other
1131           users. See also options -u and +u. In verbose mode wcd will print
1132           all filters, bans and excludes. See option -v.
1133
1134       WCDSTACKFILE
1135           Wcd gives preference to WCDSTACKFILE over the default stack file
1136           name (see section FILES). With this variable each shell (or used
1137           terminal emulator) can have its private stack of used directories.
1138
1139           To use a unique time based YYYYMMDD-HHMMSS file for each opened
1140           interactive shell.
1141
1142               export WCDSTACKFILE=$HOME/.wcd/stack.$(date +%Y%m%d-%H%M%S)
1143
1144           For a stack per xterm(1), use the xterm WINDOWID environment
1145           variable:
1146
1147               export WCDSTACKFILE=$HOME/.wcd/stack.$WINDOWID
1148
1149           For GNU screen(1), to use stack per screen:
1150
1151               export WCDSTACKFILE=$HOME/.wcd/stack.$WINDOW
1152
1153       TERMINFO
1154           If the environment variable TERMINFO is defined, wcd with ncurses
1155           interface checks for a local terminal definition before checking in
1156           the standard place. This is useful if terminal definitions are not
1157           on a standard place. Often used standard places are
1158           "/usr/lib/terminfo" and "/usr/share/terminfo".
1159
1160       PDC_RESTORE_SCREEN
1161           Wcd with PDCurses interface recognizes the environment variable
1162           PDC_RESTORE_SCREEN. If this environment variable is set, PDCurses
1163           will take a copy of the contents of the screen at the time that wcd
1164           is started; when wcd exits, the screen will be restored.  An
1165           example for Windows Command Prompt:
1166
1167               set PDC_RESTORE_SCREEN=1
1168
1169           Windows allows only a small buffer to be saved. So it is not always
1170           possible to restore everything. Some garbage data may be printed in
1171           the console after wcd exits if you have set a large buffer width.
1172
1173       SHELL
1174           Printing of "#!$SHELL" on the first line of the go-script for POSIX
1175           type shell or C shell is needed for 8 bit characters. Some shells
1176           otherwise think that the go-script is a binary file and will not
1177           source it. In Cygwin Bash the variable SHELL must be set in
1178           environment using the "export" command, otherwise wcd can't read
1179           the variable.
1180
1181       BASH
1182           Wcd for DOS bash uses $BASH instead of $SHELL, because $SHELL
1183           points to the DOS command shell. One may need to define $BASH with
1184           an "export" command, otherwise wcd can't read the variable.
1185

SEE ALSO

1187       sh(1), bash(1), csh(1), ksh(1), zsh(1), locale(1), ncurses(1),
1188

AUTHORS

1190       Wcd was written by Erwin Waterlander <waterlan@xs4all.nl>
1191
1192       Project homepage: <http://waterlan.home.xs4all.nl/>
1193
1194       SourceForge: <http://sourceforge.net/projects/wcd/>
1195
1196       The manual page formatting was provided by Jari Aalto
1197       <jari.aalto@cante.net>.
1198
1199       NCD was originally written by Brad Kingsbury for Peter Norton's "Norton
1200       Utilities" around 1987. See also
1201       <http://www.softpanorama.org/OFM/norton_change_directory_clones.shtml>
1202
1203
1204
1205wcd                               2023-04-23                            wcd(1)
Impressum