workspace-change-directory

Change the directory to a given repo in your workspace in Fish, Bash, ZSH and Nushell.

The wcd command searches for a git repo within a configured folder (default: ~/workspace) and cds into that repo if it is found. If multiple repos are found, the user is asked to pick one interactively.

Table of Contents

• Install
• Usage
• Testing
• Maintainers
• Contributing
• License

Install

There are four implementations of wcd with an identical feature set for Fish, Bash, ZSH and Nushell. All implementations come with completions.

Install wcd in Fish

This repo is an oh my fish and fisher compatible plugin repo.

To install wcd with oh my fish run:

omf install https://github.com/kfkonrad/workspace-change-directory.git

To install wcd with fisher run:

fisher install kfkonrad/workspace-change-directory

Install wcd in Bash

To install `wcd` you can download [bash/wcd.sh](https://github.com/kfkonrad/workspace-change-directory/blob/main/bash/wcd.sh) and source it in your `.bashrc`. Below are examples for installing the script using `curl` and `wget` for added convenience:

Install with curl:

mkdir -p ~/.config/
curl https://raw.githubusercontent.com/kfkonrad/workspace-change-directory/main/bash/wcd.sh -so ~/.config/wcd.sh
echo 'source ~/.config/wcd.sh' >> ~/.bashrc

Install with wget:

mkdir -p ~/.config/
wget https://raw.githubusercontent.com/kfkonrad/workspace-change-directory/main/bash/wcd.sh -qO ~/.config/wcd.sh
echo 'source ~/.config/wcd.sh' >> ~/.bashrc

Install wcd in ZSH

To install wcd you can download zsh/wcd.sh and source it in your .zshrc. Below are examples for installing the script using curl and wget for added convenience:

Install with curl:

mkdir -p ~/.config/
curl https://raw.githubusercontent.com/kfkonrad/workspace-change-directory/main/zsh/wcd.sh -so ~/.config/wcd.sh
echo 'source ~/.config/wcd.sh' >> ~/.zshrc

Install with wget:

mkdir -p ~/.config/
wget https://raw.githubusercontent.com/kfkonrad/workspace-change-directory/main/zsh/wcd.sh -qO ~/.config/wcd.sh
echo 'source ~/.config/wcd.sh' >> ~/.zshrc

Install wcd in Nushell

To install wcd you can download nushell/wcd.sh and source it in your config.nu. Below are examples for installing the script using curl and wget for added convenience:

Install with curl:

mkdir ~/.config/wcd
curl https://raw.githubusercontent.com/kfkonrad/workspace-change-directory/main/nushell/wcd.nu -so ~/.config/wcd/wcd.nu
"\nsource ~/.config/wcd/wcd.nu\n" o>> $nu.config-path

Install with wget:

mkdir ~/.config/wcd
wget https://raw.githubusercontent.com/kfkonrad/workspace-change-directory/main/nushell/wcd.nu -qO ~/.config/wcd/wcd.nu
"\nsource ~/.config/wcd/wcd.nu\n" o>> $nu.config-path

Usage

You can configure wcd with the following environment variables:

• WCD_BASE_DIR: Base directories to search. If unset it defaults to ~/workspace. Multiple base directories are supported via the : separator, e.g. WCD_BASE_DIR='~/workspace:/mnt/projects'
• WCD_REPO_MARKERS: Colon-separated list of files or directories that mark a repository. Defaults to .git. Examples: .git:.hg:.svn or Cargo.toml:package.json:pom.xml
• WCD_DEBUG: When set to any non-empty value, prints debug information to stderr showing which directories are being visited during the search, which are skipped (and why), and which repositories are found. Useful for troubleshooting or understanding how wcd traverses your workspace

wcd <repo-name>
wcd --no-ignore <repo-name>
wcd -u <repo-name>

wcd only finds repos if the name fully matches wcd's argument, i.e. passing partial names will not find a match.

When WCD_REPO_MARKERS is set, a directory is considered a repository if it contains any of the listed marker files/directories. This affects both navigation and completions in all supported shells.

wcd also supports ignoring directories. To do so create an empty file called .wcdignore in the directory you wish to ignore. This directory and any subdirectories won't be listed in completions and can't be cdd into with wcd.

Use the --no-ignore flag (or its short form -u) to bypass .wcdignore files and search in all directories, including those that would normally be ignored.

Examples

1. Assume the directory ~/workspace/foo/bar/baz exists and is a git repo. Running wcd baz will cd into ~/workspace/foo/bar/baz

2. Assume that ~/workspace/a/foo and ~/workspace/b/foo are both repos. Running wcd foo will ask the user to pick one of the repos like so:

   Multiple repositories found. Please select one:
    1: /home/kfkonrad/workspace/a/foo
    2: /home/kfkonrad/workspace/b/foo
    Enter your choice:

   By typing in the number of your desired repo and pressing enter wcd with cd there.

3. Assume that no repo called foo exists in ~/workspace or you have WCD_BASE_DIR set to a non-existent directory or ~/workspace doesn't exist. Running wcd foo will print the following error message:

   Repository not found.

4. Assume the directory ~/workspace/foo/bar/ exists and is a git repo. Assume further than either a file ~/workspace/.wcdignore or ~/workspace/foo/.wcdignore or ~/workspace/foo/bar/.wcdignore (or any combination of them) exists. Running wcd bar will print the following error message:

   Repository not found.

5. Continuing from the previous example, running wcd --no-ignore bar or wcd -u bar will bypass the .wcdignore files and successfully cd into ~/workspace/foo/bar/ despite the ignore files being present.

6. To see debug output showing which directories wcd visits during its search:

   WCD_DEBUG=1 wcd foo

   This will output (to stderr) something like:

   [DEBUG] Starting search for 'foo' in: /home/user/workspace
   [DEBUG] Visiting:          /home/user/workspace
   [DEBUG] Visiting:          /home/user/workspace/bar
   [DEBUG] Skipped (is repo): /home/user/workspace/bar
   [DEBUG] Visiting:          /home/user/workspace/company
   [DEBUG] Visiting:          /home/user/workspace/company/foo
   [DEBUG] Found repo:        /home/user/workspace/company/foo

Testing

The test suite validates wcd functionality across all supported shells (Bash, ZSH, Fish, Nushell) using Docker containers and pytest.

Requirements

• Bash
• Docker
• Python 3

Running Tests

cd tests
./test.sh

The test script automatically sets up Docker containers for each shell, creates test repositories, installs dependencies in a venv, runs the full test suite and cleans up the containers, test repos and venv.

Maintainers

@kfkonrad

Contributing

PRs accepted.

Small note: If editing the README, please conform to the standard-readme specification.

License

MIT © 2025 Kevin F. Konrad