Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/dvigo/zsh-dev-navigator

Quickly jump into your development directories using a simple command that acts as a smart cd with recursive autocompletion. It also supports additional options to extend its functionality, such as integrating with external tools or performing common project tasks directly from the terminal.
https://github.com/dvigo/zsh-dev-navigator

hacktoberfest

Last synced: 3 months ago
JSON representation

Quickly jump into your development directories using a simple command that acts as a smart cd with recursive autocompletion. It also supports additional options to extend its functionality, such as integrating with external tools or performing common project tasks directly from the terminal.

Awesome Lists containing this project

README 

          
# zsh-dev-navigator



A minimal **Zsh plugin** that lets you quickly jump into your development directories with a single command.  

`dev` acts as a smart replacement for `cd`, allowing you to navigate into project folders instantly with **recursive autocompletion** — and even open them directly in **VS Code**.



---



## ⚡ Quick Start



```bash

dev api-server

# → cd ~/dev/api-server

```



Or open the project in your configured editor:



```bash

dev -o api-server

# → Opens ~/dev/api-server in your configured editor (default: VS Code)

```



Create a new project directory:



```bash

dev -c new-project

# → Creates ~/dev/new-project and navigates to it

```



Create a new project with git repository:



```bash

dev -cg new-project

# → Creates ~/dev/new-project, initializes git, and navigates to it

```



Execute a file (with confirmation):



```bash

dev script.sh

# → Asks for confirmation, then executes ~/dev/script.sh

```



Execute a file with arguments:



```bash

dev test.sh -ac --verbose

# → Target is a file: ~/dev/test.sh

# → With arguments: -ac --verbose

# → Do you want to execute this file? [y/N]: y

# → Executes: ~/dev/test.sh -ac --verbose



# Or interactively:

dev test.sh

# → Do you want to execute this file? [y/N]: y

# → Enter arguments (or press Enter for none): -ac --verbose

# → Executing with arguments: -ac --verbose

```



Open a file in editor:



```bash

dev -o config.json

# → Opens ~/dev/config.json in your configured editor

```



---



## ✨ Features



- ⚡ Quickly `cd` into any development project with a simple command.  

- 📁 Smart **recursive autocompletion** for subfolders.  

- 🧭 Defaults to your base development folder when no argument is provided.  

- 🪄 Optional **flags** to extend functionality — e.g., open projects directly in your **preferred editor**.  

- 🆕 **Create new project directories** on-the-fly with the `-c` flag.

- 🔧 **Initialize git repositories** automatically with the `-cg` flag.  

- ⚙️ **Configurable** base directory and default editor via configuration file.  

- 🤖 **Auto git init** option to initialize git repositories with `-c` flag automatically.

- 📄 **File execution support** with confirmation prompts for executable files.

- 📝 **File editing** with `-o` flag to open files directly in your configured editor.

- 🧠 **Intelligent file/directory detection** based on file extensions.

- 🆕 **File creation** with automatic parent directory creation.

- 🔄 **Fallback mode** for users without fzf installed.  

- 🔍 **Fuzzy finder integration** (fzf) for interactive project selection when no argument is provided.  

- 🎯 Support for **multiple editors**: VS Code, Cursor, Windsurf, Sublime Text, Vim, and more.  



---



## 📦 Installation



### **Oh My Zsh**



1. Clone the plugin into your Oh My Zsh custom plugins folder:



   ```bash

   git clone https://github.com/dvigo/zsh-dev-navigator.git ~/.oh-my-zsh/custom/plugins/zsh-dev-navigator

   ```



2. Enable it in your `~/.zshrc`:



   ```bash

   plugins=(... zsh-dev-navigator)

   ```



3. Reload Zsh:



   ```bash

   source ~/.zshrc

   ```



---



## 🎥 Demo



**Basic usage:**  

```bash

dev api-server

```



**Result:**  

```

📂 Moved to: ~/dev/api-server

```



**Autocompletion:**  

Start typing and press `` to explore all projects and subfolders:



```

dev fr

# frontend-app

# frontend-utils

# frontend-tests

```



**Open in your preferred editor:**  

```bash

dev -o frontend-app

# → Opens ~/dev/frontend-app in your configured editor (e.g., Cursor, VS Code, etc.)

```



**Interactive project selection with fuzzy finder:**  

```bash

dev

# → Opens fzf interface to select from available projects

# → Press ESC to navigate to the root dev folder

```



**Create new project:**  

```bash

dev -c new-project

# → Creates ~/dev/new-project and navigates to it

```



**Create new project with git:**  

```bash

dev -cg new-project

# → Creates ~/dev/new-project, initializes git, and navigates to it

```



---



## ⚙️ Configuration



The plugin uses a configuration file located in the plugin directory. You can customize the following settings:



### Configuration File



The plugin includes a `config` file with the following options:



```bash

# Development directory - where your projects are located

# This can be an absolute path or use ~ for home directory

dev_directory = ~/dev



# Default editor to use with the -o flag

# Supported editors: code, cursor, windsurf, subl, vim, nvim, emacs, atom, webstorm, idea, pycharm

editor = code



# Automatically initialize git repository when creating new directories with -c flag

# Set to true to enable automatic git init, false to disable

auto_git_init = false

```



### Customizing Settings



1. **Development Directory**: Change the `dev_directory` setting to point to your projects folder:

   ```bash

   dev_directory = ~/Development

   dev_directory = /path/to/your/projects

   ```



2. **Default Editor**: Set your preferred editor for the `-o` flag:

   ```bash

   editor = cursor        # Cursor editor

   editor = windsurf      # Windsurf editor  

   editor = code          # VS Code

   editor = subl          # Sublime Text

   editor = vim           # Vim

   editor = nvim          # Neovim

   ```



3. **Custom Editor Path**: You can also specify a full path to a custom editor:

   ```bash

   editor = /usr/local/bin/my-custom-editor

   ```



4. **Automatic Git Initialization**: Enable automatic `git init` when creating directories with `-c`:

   ```bash

   auto_git_init = true   # Always initialize git with -c flag

   auto_git_init = false  # Only initialize git with -cg flag (default)

   ```



---



## 🖊️ Usage



Basic syntax:



```bash

dev 

```



Examples:



```bash

dev dashboard-ui

# → cd ~/dev/dashboard-ui



dev api-server/routes

# → cd ~/dev/api-server/routes



dev

# → cd ~/dev

```



Open a project in your configured editor:



```bash

dev -o api-server

# → Opens the project in your configured editor (Cursor, VS Code, etc.)

```



Create a new project directory:



```bash

dev -c new-project

# → Creates ~/dev/new-project and navigates to it

```



Create a new project with git repository:



```bash

dev -cg new-project

# → Creates ~/dev/new-project, initializes git, and navigates to it

```



**Note**: If you have `auto_git_init = true` in your config, then `dev -c new-project` will also initialize git automatically.



Combine flags:



```bash

dev -c -o new-app

# → Creates ~/dev/new-app and opens it in your configured editor



dev -cg -o new-git-project

# → Creates ~/dev/new-git-project, initializes git, and opens it in your editor

```



---



## 📄 File Handling



The plugin now supports working with files in addition to directories:



### File Execution

When targeting a file, the plugin will ask for confirmation before execution:



```bash

dev script.sh

# → Target is a file: ~/dev/script.sh

# → Do you want to execute this file? [y/N]: y

# → Executes the file and navigates to its directory

```



**With arguments:**

```bash

dev deploy.sh --env production --force

# → Target is a file: ~/dev/deploy.sh

# → With arguments: --env production --force

# → Do you want to execute this file? [y/N]: y

# → Executes: ./deploy.sh --env production --force

```



**Interactive argument input:**

```bash

dev script.sh

# → Target is a file: ~/dev/script.sh

# → Do you want to execute this file? [y/N]: y

# → Enter arguments (or press Enter for none): -v --debug

# → Executing with arguments: -v --debug

# → Executes: ./script.sh -v --debug

```



**Use cases:**

- Run scripts with flags: `dev test.sh -v`

- Pass configuration: `dev build.sh --config prod`

- Multiple arguments: `dev script.sh arg1 arg2 arg3`

- Interactive mode: `dev script.sh` → then enter arguments when prompted



### File Editing

Use the `-o` flag to open files directly in your configured editor:



```bash

dev -o config.json

# → Opens ~/dev/config.json in your editor

# → Navigates terminal to ~/dev/ directory

```



### Creating New Files

The plugin intelligently detects when you're trying to work with files and offers to create them:



**With `-o` flag (create and edit):**

```bash

dev -o new-config.json

# → File does not exist: ~/dev/new-config.json

# → Do you want to create this file? [y/N]: y

# → Created and opened file in your editor

```



**Without flags (create and optionally execute):**

```bash

dev new-script.sh

# → File does not exist: ~/dev/new-script.sh

# → Do you want to create this file? [y/N]: y

# → File created: ~/dev/new-script.sh

# → Do you want to execute this file? [y/N]: n

```



### Files in Subdirectories

The plugin automatically creates parent directories when needed:



```bash

dev -o src/components/Header.jsx

# → Creates src/components/ directory if it doesn't exist

# → Creates and opens Header.jsx in your editor

```



### Intelligent Detection

The plugin automatically detects whether you're working with files or directories:



**Files (with extensions):**

- `script.sh`, `config.json`, `README.md` → Treated as files

- Offers creation, execution, or editing options



**Directories (without extensions):**

- `my-project`, `frontend-app`, `api-server` → Treated as directories  

- Suggests using `-c` flag for creation



### Restrictions

- **Creation flags (`-c`, `-cg`) cannot be used with files**

- **fzf selection with `-c`/`-cg` shows only directories**

- **Autocompletion with `-c`/`-cg` shows only directories**



---



## 📌 Autocompletion



The `dev` command includes powerful autocompletion for all subdirectories inside your base development folder.  



Just type part of a project name and press `` to complete it.



## 🔍 Fuzzy Finder Integration



When you run `dev` without any arguments, the plugin provides different interfaces based on availability:



### With fzf (Enhanced Experience)

If **fzf** is installed, you get an interactive selection interface:



- Browse through all your projects with fuzzy search

- Use arrow keys or type to filter projects

- Press **Enter** to navigate to the selected project

- Press **ESC** to navigate to the root development folder instead



### Without fzf (Fallback Mode)

If **fzf** is not available, the plugin shows a list and prompts for input:



```bash

dev

# → Available projects in ~/dev:

# → api-server

# → config.json

# → frontend-app

# → script.sh

# → Enter project/file name (or press Enter for root directory): new-file.txt

```



### Smart Filtering

The interface adapts based on the flags used:

- **Regular navigation**: Shows both files and directories

- **With `-c` or `-cg`**: Shows only directories (prevents file creation conflicts)



---



## 🔧 Roadmap



- [x] Add flag to create new project directories.  

- [x] Add flag to open projects directly in editors.  

- [x] Add support for multiple editors (VS Code, Cursor, Windsurf, Sublime, Vim, etc.).  

- [x] Add fuzzy search for project names with fzf integration.  

- [x] Add configuration file system for customizable settings.  

- [ ] Add aliases or shortcuts per project.  

- [ ] Add project templates for new directory creation.  



---



## 📜 License



GNU General Public License v3.0 — See [LICENSE](LICENSE) for details.