Venver
######

Automatically activate, and deactivate virutal environments when entering or
leaving directories.

Installation
############

.. code-block:: shell

    curl -LsSf https://codeberg.org/narvin/venver/raw/branch/main/bin/install.sh | sh

Once finished, the installation script will print additional instructions to
configure your shell.

Usage
#####

Let's assume you have a python project with a virtual environment like this:

.. code-block::

    ~/
    ├─ myapp/
    │  ├─ .venv/
    │  │   ...
    │  ├─ src/
    │  │   ...
    │  ├─ .gitignore
    │  ├─ pyproject.toml
    │  ├─ README.rst

Add a ``.venver`` file to the project root.

.. code-block:: shell

    cd ~/myapp
    echo './.venv' > .venver

.. code-block::

    ~/
    ├─ myapp/
    │  ├─ .venv/
    │  │   ...
    │  ├─ src/
    │  │   ...
    │  ├─ .gitignore
    │  ├─ .venver
    │  ├─ pyproject.toml
    │  ├─ README.rst

Navigating anywhere inside the ``myapp`` directory will result in the
environment at ``myapp/.venv`` being activated. And navigating outside of
``myapp`` will deactivate the environment.

.. code-block:: console

    ~ $ cd myapp
    ~/myapp (.venv) $ cd src
    ~/myapp/src (.venv) $ cd ~
    ~ $ cd myapp/src
    ~/myapp/src (.venv) $

If you manually deactivate the environment, it won't be automatically activated
again until you navigate outside of ``myapp``, then reenter it.

.. code-block:: console

    ~ $ cd myapp
    ~/myapp (.venv) $ deactivate
    ~/myapp $ cd src
    ~/myapp/src $ cd ~
    ~ $ cd myapp
    ~/myapp (.venv) $

You may specify an environment that isn't in the project directory. This is
useful if you have environments you want to reuse. The activation, and
deactivation will still be relative to the ``.venver`` directory, and not the
environment directory.

.. code-block::

    ~/
    ├─ venvs/
    │  ├─ web-venv/
    │  │   ...
    │  ├─ console-venv/
    │  │   ...

.. code-block:: shell

    cd ~/myapp
    echo '~/venvs/web-venv' > .venver

.. code-block:: console

    ~ $ cd myapp
    ~/myapp (web-venv) $ cd src
    ~/myapp/src (web-venv) $ cd ~
    ~ $ cd myapp/src
    ~/myapp/src (web-venv) $
