Why change the search path?
It might be that you have all your data stored in a particular directory. In such a case, it would probably be a good idea to add that directory (and any subdirectories which you need to search) to the search path. Similarly, if you are studying your own models, you could put them all in one directory, and add that directory to the search path. [You should probably make these directories absolute, so that Cold can find the files wherever you run it from.]
How can I change the search path?
There are three ways:
The first option will change the search path every time you run the program. The second will also change the search path every time you run the program, but the options in your personal variable file can easily be all added, or all removed together, so if you have a set of options that you use for some program runs, but not others, then you could put these in a variable file and use the --variables commandline option (see -variables) whenever you want to use those options. The third option will set the search path just for the current run.
How should I format the search path?
The search path just consists of a list of directories, separated by the colon character :. If the directory name contains a colon, you can precede the colon with a backslash \. This means that in order to have a backslash in your directory name, you need to precede it by a backslash as well (so it would be ‘\\’). [Note that if specifying the path variable on the command line, your commandline may give special significance to certain characters, which may therefore need to be escaped (often by preceding them with a backslash, or by putting them in quotation marks). [For example, on linux, if you want to specify a search path on the command line, and one of the directory names contains a colon, you would have to precede that colon with a backslash, but the shell would remove the backslash, so you would need to precede it by another backslash.] Directory names containing new line characters are not supported, and probably never will be.
Even if I'm only using files in the search directories for some runs, couldn't I just leave all the interesting directories in the search path for every run?
This is probably OK. There are a few issues.
When using the -f option, the search algorithm works slightly differently. It still searches directories in the order above. For each directory, it first searches for the file as typed. Then it searches for the file with each of the allowed file extensions. [The defaults are ‘.tree’, ‘.tree.1.txt’, ‘.tree.txt’, and ‘.txt’ for tree files, and ‘.seq’, ‘.nuc.txt’, ‘.dat’, and ‘.txt’ for sequence files. Currently, these can only be changed by modifying the fileExtensions.h file before compiling the program. I expect that later versions of Cold will allow it to be set more easily.]
It then compiles a list of all the possibilities, in the order listed above. Once it has the lists for data and tree files, it considers using the first possible tree file as a tree file, and checks whether this would allow it to find a data file. If it would, then it opens this tree file and opens the first remaining data file. Otherwise, it tries the next tree file, which should allow it to find a data file. If not, it will keep trying (but in this case, it should not manage to find a tree and data file).
[Note that the program does not make any checks on the contents of the files. It simply chooses the file names. If it tries to open a data file as a tree file or vice-versa, it will almost certainly abort with an error message. Hopefully, later versions of Cold will have more sophisticated methods for checking file type, and will be able to resolve more cases like this.]