mirror of
https://github.com/ohmyzsh/ohmyzsh.git
synced 2026-01-30 02:44:42 +01:00
105 lines
3.6 KiB
Markdown
105 lines
3.6 KiB
Markdown
# Viper Env Z-Shel plugin
|
|
|
|
Automatically activates and deactivates python virtualenv upon cd in and out.
|
|
|
|
## Features
|
|
|
|
- **Automatic Activation/Deactivation:** Finds and manages virtualenvs in your project directories as you `cd`.
|
|
- **Upward Search:** Works even if you are in a subdirectory of your project.
|
|
- **Plays Well With Others:** If a `viper-env` managed environment is active and you `cd` into a new project, it will correctly deactivate the old one before activating the new one.
|
|
- **Convenient Manual Activation:** When autoloading is disabled, an `activate` alias is automatically made available in project directories, giving you explicit control.
|
|
- **State-Aware:** Only deactivates environments that it has activated, so it won't interfere when you leave a project that uses another tool.
|
|
- **Configurable Autoloading:** Easily enable or disable the automatic activation/deactivation feature.
|
|
- **Diagnostic Commands:** Supports a quiet mode and provides `list`, `status`, and `version` commands for diagnostics.
|
|
|
|
## Inspiration
|
|
|
|
Based on [blueray](https://stackoverflow.com/users/1772898/blueray)'s [answer](https://stackoverflow.com/a/63955939/11685534), I decided to go one step further and implement it as a Z-Shell plugin.
|
|
|
|
## Usage
|
|
<!-- [](https://asciinema.org/a/4iMwcKfBS1dc1EgI1FihrDVxT) -->
|
|
|
|
|
|
|
|
## Usage
|
|
|
|
### Automatic Mode (Default)
|
|
|
|
By default, `viper-env` is configured for a seamless experience. It uses a `precmd` hook that runs before each prompt, allowing it to activate virtual environments immediately upon creation or when you enter a project directory.
|
|
|
|
```zsh
|
|
# Create a new project and cd into it
|
|
mkdir my-project && cd my-project
|
|
|
|
# Create a virtual environment
|
|
python -m venv .venv
|
|
# -> Activating virtual environment .venv
|
|
|
|
# Go to a subdirectory
|
|
mkdir src && cd src
|
|
# -> ".venv" stays active
|
|
|
|
# Leave the project directory
|
|
cd ../..
|
|
# -> viper-env automatically deactivates ".venv"
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Using External Virtual Environments (Semi-Automatic Mode)
|
|
|
|
> [!TIP]
|
|
> For projects where you prefer to keep the virtual environment directory outside of the project folder (e.g., in `~/.virtualenvs/`), you can use the semi-automatic mode.
|
|
>
|
|
> Create a file named `.viper-env` in your project's root directory and place the **absolute path** to your virtual environment in it.
|
|
>
|
|
> ```sh
|
|
> # Example: Tell viper-env to use the 'my-project-venv' environment for this project
|
|
> echo "/home/user/.virtualenvs/my-project-venv" > .viper-env
|
|
> ```
|
|
> `viper-env` will prioritize this file over automatically discovered venvs.
|
|
|
|
### Disabling and Enabling Autoloading
|
|
|
|
If you wish to temporarily disable the automatic activation and deactivation behavior, you can use the `autoload --disable` command. This acts as a master switch.
|
|
|
|
```zsh
|
|
viper-env autoload --disable
|
|
```
|
|
|
|
With autoloading disabled, `viper-env` will not perform any actions as you change directories. You can re-enable the automatic behavior at any time:
|
|
|
|
```zsh
|
|
viper-env autoload --enable
|
|
```
|
|
|
|
## Instalation
|
|
|
|
### Oh my Zsh
|
|
|
|
Git clone this repository to the Oh my Zsh custom plugins folder.
|
|
|
|
Add plugin to plugins directive in `~/.zshrc`
|
|
```zsh
|
|
plugins=(
|
|
# put local oh-my-zsh plugins here
|
|
viper-env
|
|
)
|
|
|
|
source $HOME/.oh-my-zsh/oh-my-zsh.sh
|
|
```
|
|
|
|
### Antigen
|
|
It is recommended to use a `.antigenrc` file. Then add the following to it:
|
|
|
|
```zsh
|
|
antigen bundle DanielAtKrypton/viper-env
|
|
|
|
# Apply changes
|
|
antigen apply
|
|
```
|
|
|
|
Make sure in your `.zshrc` Antigen is loading the `.antigenrc` file as follows:
|
|
```zsh
|
|
antigen init ~/.antigenrc
|
|
```
|