qcd is a bash utility that extends upon the exisiting capabilities of the builtin command cd. It allows the user to quickly change from one directory to another by specifying a directory path, directory name alias, directory name prefix, or directory name subsequence to the program as a command line argument. qcd works completely locally and utilizes common builtin commands to achieve this functionality, making it extremely portable across systems that run bash. qcd operates out of the directory ~/.qcd and remembers which directories you visit by storing symbolic linkages on disk. This file allows qcd to quickly search for and resolve the absolute path from a symbolic linkage and switch to that directory given a recognizable input.
qcd is compatible with macOS and popular Linux distributions in bash environments from v3.x onwards.
qcd does not require any special dependencies to operate as a command line utility and uses common builtin commands during normal execution. However, there are some optional dependencies that may be missing depending on the operating system qcd is installed on. Some operating systems do not natively ship with the curl binary which is used by qcd to download updates. While you can install this dependency using a tool like apt or brew, it is not essential to have this dependency installed as all qcd installations can be upgraded with the install.sh script that comes packaged with each release.
Please navigate to the release page of this repository and download the latest version of qcd. This download can be done within a browser environment or using a command line program like wget or curl as shown below, assuming they are installed.
# Using wget
command wget https://github.com/nalinahuja/qcd/archive/v3.2.zip
# Using curl
command curl -sL https://github.com/nalinahuja/qcd/archive/v3.2.zip > v3.2.zipAlternatively, you can clone this repository but it is recommended that you download the most recent release of qcd since the repository is comparatively larger in size.
Navigate to the location where qcd has been downloaded onto your machine, unzip the archive if needed, and run the install.sh script. This executable will install qcd into the directory ~/.qcd and add the qcd command to your terminal profile. When the installation finishes, please restart your terminal to fully configure the installation.
If you would like to do a manual installation of qcd, all you need to do is move the program files you downloaded, besides the install.sh file, into a directory named ~/.qcd which you will have to create yourself. Then restart your terminal after adding the following command to your terminal profile.
command source ~/.qcd/qcd.shTo manually update qcd to a newer release, simply follow the same installation process or use the update flag as described in the flags section below. Don't worry, updating qcd won't modify any directory linkages you have created.
Just like the builtin command cd, you can specifiy either an absolute or relative path as a command line argument and qcd will navigate to it. Where qcd differs from cd is that you can indicate a keyword, prefix, or subsequence related to a directory that qcd has previously seen and the program will attempt to resolve that directory's absolute path and navigate to it.
# Standard Input # Special Input
qcd [dir] qcd [keyword, prefix, subsequence]
When a keyword is passed to qcd as input, the program will attempt a case sensitive search for the matching directory. When passing a prefix or character subsequence to qcd as input, the program will attempt a case insensitive search for the matching directory. In the latter input format, the input must start with the first character of the linked directory you wish to navigate to since qcd expects a subsequence rooted at the first character of the directory you wish to navigate to.
Assume for the following examples that a non-local directory node-modules exists and a linkage has been created for it.
# Path Example # Keyword Example # Prefix Example # Subsequence Example
qcd ./../node-modules qcd node-modules qcd node qcd nm
qcd is able to interpret standard file system characters and sequences like ~, /, . and .. just like the builtin cd command.
# File System Sequences
qcd ~/./../[dir]
qcd can also interpet some special input formats that the builtin cd command does not natively support. qcd can accept a path to a file that exists on disk and jump to the directory that this file exists in by extracting the directory name from the file path. qcd can also accept input in the format n.. which will tell it to jump to the nth parent directory relative to the present working directory.
# File Path Handling # nth Parent Directory
qcd [file] qcd [n]..These usages can be viewed anytime using the help flag described in the usage section below.
qcd ships with a custom completion engine that can be activated by hitting the tab key twice. Much like the builtin command cd, this completion engine is able to complete directories of the present working directory and their subdirectories as well as interpret file system sequences like ~, /, . and .. during completion. qcd builds upon these standard features to allow for the completion of directories not in the present working directory using information qcd has stored away. It is also able to complete subdirectories of linked directories based on a keyword, prefix, or subsequence.
Assume for the following examples that a non-local directory node-modules exists and a linkage has been created for it.
# Keyword Example # Prefix Example # Subsequence Example
qcd node-modules/<tab><tab> qcd node/<tab><tab> qcd nm/<tab><tab>
If multiple paths are resolved from same command line argument, the user will have to manually choose the path they wish to navigate to from an arrow key navigable menu which can be cleanly exited from by either pressing the q key or sending a SIGINT to the program. There are several redundancies built into the program to simplify or entirely avoid manual intervention from the user in order to streamline the use of qcd.
qcd offers many different flags that are important to smoothening user experience.
The remember flag allows the user to add a symbolic linkage to disk. Without any arguments, qcd will add the linkage that corresponds to the present working directory. The user can specify a valid path after the remember flag to add a linkage specific to that path.
# No Arguments # With Path
qcd [-r, --remember] qcd [-r, --remember] [dir]In both usages, the linkage keyword is automatically derived from the directory path. To set a custom linkage keyword, please see the alias flag usage.
The alias flag allows the user to remember the present working directory by a custom linkage keyword. This flag can be used as many times as the user desires on directories that qcd has already stored linkages for to update their respective keywords.
# With Alias
qcd [-a, --alias] [alias]The alias flag can be used in conjunction with the remember flag to alias relative directories.
# With Remember Flag
qcd [-a, --alias] [alias] [-r, --remember] [dir]
The forget flag allows the user to remove a symbolic linkage from disk. Without any arguments, qcd will remove the linkage that corresponds to the present working directory. The user can specify a valid path or keyword after the forget flag to remove all matching symbolic linkages.
# No Arguments # With Path # With Keyword
qcd [-f, --forget] qcd [-f, --forget] [dir] qcd [-f, --forget] [keyword]
The options flag displays the paths of symbolic linkages in qcd has stored that match the specified query argument in a manually selectable menu for more precise directory navigation. The query argument can be a keyword, prefix, or subsequence related to symbolic linkages in qcd has stored on disk.
qcd [-o, --options] [query]The back directory flag allows the user to swtich back to the directory they most recently switched from.
qcd [-b, --back-dir]
The make directory flag allows the user to create a directory at a specified path and automatically switch to that directory once it is created. qcd internally stores a symbolic linkage on disk that corresponds to the new directory if directory tracking is enabled, which is explained in the track flag section.
qcd [-m, --make-dir]
The track directories flag allows the user to toggle the directory tracking behavior of qcd. When directory tracking is enabled, qcd will automatically store new directories on disk as they are visited. This feature is disabled by default.
qcd [-t, --track-dir]
The clean flag removes symbolic linkages qcd has stored on disk that correspond to directories that may have been renamed or deleted. qcd automatically cleans the lookup file at the start of each bash session, so it is not necessary to manually clean the lookup file too often.
qcd [-c, --clean]
The list flag outputs the current symbolic linkages qcd has stored on disk sorted by keyword.
qcd [-l, --list]
qcd supports a set of standard flags such as the help, version, and update flags.
# Help Flag # Version Flag # Update Flag
qcd [-h, --help] qcd [-v, --version] qcd [-u, --update]