The $CDPATH Environment Variable

You already know what the PATH environment variable is. CDPATH works in a similar same way. It helps you change into a subdirectory of a known parent in your CDPATH.

Why Configure a CDPATH?

Most people have a few things they work with on a daily basis and it’s common for those things to be grouped together into a broader classification like ~/projects/[project]. If you’re like me, you might break things down a bit further, separating personal projects from work-related projects.

For example, I use ~/projects/jaswrks/[project] for my personal projects, and I keep projects related to WebSharks in ~/projects/websharks/[project].

Since I work with projects in one of these main folders all the time, wouldn’t it be nice if I could just type the name of a project and go straight to that project’s subdirectory? With CDPATH that’s possible.

How to Configure CDPATH?

By default, your CDPATH is empty, but you can easily customize.

Like the PATH environment variable, it’s a : separated list of locations in order of priority. So, for example, if you type cd [project], the first location in your CDPATH will be checked first, then the next, and so on; until the [project] subdirectory is found. That’s where you’ll be moved to.

So before you configure a CDPATH, it’s good to analyze your home directory structure and think about your work habits. Ask yourself, “what main directories do I use to group things together and stay organized?”.

My Home Directory Example

This is a quick look at the structure of my home directory.

  • Users/jaswrks/
    • VMs/
      • nginx.vm/
      • apache.vm/
    • projects/
      • jaswrks/
        • chai/
        • shields/
        • liquidjs/
        • …etc.
      • websharks/
        • wp-snippets-pro/
        • comet-cache-pro/
        • …etc.

My CDPATH Example

Note: I added this to my ~/.profile startup script.

export CDPATH=.\
:~\
:~/vms\
:~/projects/jaswrks\
:~/projects/websharks;
  • It starts by giving the current directory top priority: .
  • Next, it gives my home directory second highest priority.
  • I work with several VMs, so next comes my ~/vms directory.
  • Then my personal projects directory: ~/projects/jaswrks
  • And finally, my work-related projects: ~/projects/websharks

So my preference is to include all of my parent project directories. Why? Because I visit subdirectories inside of those all the time while working on repos. No matter where I’m currently at, when I change directories I can simply type the name of a folder that’s in one of those common locations.

Testing My CDPATH Example

Given the above configuration, no matter what directory I’m currently in, I can simply type the name of a project subdirectory. CDPATH will be scanned automatically and I’ll be magically beamed over to that project’s deeply nested and well-organized location on my system.

$ cd liquidjs
# Discovers ~/projects/jaswrks/liquidjs

Tip: If you have Bash/Zsh auto-complete installed and configured too, those will be CDPATH-aware. So I could simply type:

$ cd liq[TAB]
# [TAB] expands to: liquidjs
# Discovers ~/projects/jaswrks/liquidjs

Difference Between PATH and CDPATH

PATH works with nearly all commands, while CDPATH only works for cd.

Where Should I Define CDPATH?

I suggest adding it to your ~/.profile, but please see:

Caution: CDPATH is purely for interactive use. Depending on your system, the selected implementation method, and whether you ‘export’ or just define CDPATH, it may have the unfortunate side effect of breaking some utilities implemented as shell scripts.

There are two effects shell script authors might not be prepared for. 1) cd suddenly jumps to unexpected directories; 2) it writes text to the standard output.

If CDPATH is set, will the cd command still search in the current directory by default, before referring to the CDPATH?

No. Once CDPATH is set, the cd command will only search directories in your CDPATH. Therefore, it’s your responsibility to make sure the current directory is given top priority. Note the . in my example.

export CDPATH=.\
:~\
:~/vms\
:~/projects/jaswrks\
:~/projects/websharks;

How can I find the current value of CDPATH?

$ echo $CDPATH

Related Articles

Share This
Posted in: