# envf

envf runs a program with modified environment variables.
It is similar to Unix `env` but also supports reading from `dotenv`-style files.

The dotenv file parser currently used is [`dotenvy`](https://crates.io/crates/dotenvy); please refer to its documentation for the file syntax.

**envf project links:** [homepage](https://gitlab.com/sjohannes/envf), [crates.io](https://crates.io/crates/envf).

## Usage

envf takes any number of `NAME=VALUE` environment variable definitions, followed by the program you wish to run and its arguments.

```sh
$ envf NAME=VALUE sh -c 'echo $NAME'
VALUE
```

To read from a `dotenv`/`.env`-style file, use the `-f` option followed by the file path.
Unlike some similar programs, envf will not automatically read environment variables from `.env` files, because explicit is better than implicit.

```sh
$ echo NAME=VALUE > my-env

$ envf -f my-env sh -c 'echo $NAME'
VALUE
```

If run with no program specified, envf shows the environment variables that would be used if you were to specify a program.

```sh
$ envf NAME=VALUE
HOME=/home/user
NAME=VALUE
PATH=/usr/bin:/bin
...
```

For full usage documentation, see the output of `envf --help`.
envf supports the `-i` option from POSIX `env` as well as the `-0` and `-u` extensions that are present on GNU and FreeBSD.

Although envf follows many of the behavior and options from POSIX `env` and its implementations, it is not fully compatible.
For example, envf quotes problematic variable names and values when printing them.

```bash
$ env -i NAME1=VALUE1 $'NAME2=\nVALUE2' 'NAME3="VALUE3"'
NAME1=VALUE1
NAME2=
VALUE2
NAME3="VALUE3"

$ envf -i NAME1=VALUE1 $'NAME2=\nVALUE2' 'NAME3="VALUE3"'
NAME1=VALUE1
NAME2="\nVALUE2"
NAME3="\"VALUE3\""
```

# Building & testing

To build envf, you need a Rust toolchain; see the `rust-version` field in `Cargo.toml` for the minimum version.
Then run `cargo build --release` to produce an `envf` executable in `target/release`.

To test envf, you also need Python and pytest.
Then run `cargo test && pytest test.py`.

# Contributing

By contributing, you agree to license your contributions under the same license as this project (see the `license` field in `Cargo.toml`).