Documentation on .env files and load_dotenv is still confusing

[sblask]

Describe the bug

I am new to direnv, so correct me if I am wrong, but from what I tried (using the latest binary on Mac) and if I understand it correctly, you can either have a .envrc OR an .env loaded automatically by direnv. For the latter to work you need to set load_dotenv to true. But the documentation makes it sound like both are loaded:

Before each prompt, direnv checks for the existence of a .envrc file (and [optionally](https://github.com/direnv/direnv/blob/master/man/direnv.toml.1.md#load_dotenv) a .env file) in the current and parent directories. If the file exists (and is authorized), it is loaded into a bash sub-shell and all exported variables are then captured by direnv and then made available to the current shell.

This should probably read:

... (or, [if enabled](https://github.com/direnv/direnv/blob/master/man/direnv.toml.1.md#load_dotenv), a .env file) ...

And this:

load_dotenv
Also look for and load .env files on top of the .envrc files. If both .envrc and .env files exist, the .envrc will always be chosen first.

should probably read:

Also look for and load .env files. If both .envrc and .env files exist, only the .envrc will be used.

This seems out of place:

Note that this functionality is not supported in .env files. If the coexistence of both is needed, one can use .envrc for leveraging stdlib and append dotenv at the end of it to instruct direnv to also read the .env file next.

It would probably be good to have an extra section just explaining the precedence of .envrc and .env and how things work when there is something in the current and in parent directories. I'd create a PR, but I am not sure how the latter works.

[sblask]

I wrote "still" because I saw there was an issue before #941

[zimbatm]

The best is to write dotenv in the .envrc so the .envrc loads the .env file. And ignore the load_dotenv config option. It seemed like a good idea at the time, but it broke backward compatibility and is really adding more confusion than necessary.

[sblask]

@zimbatm Sure, but as long as the feature is there it should be documented properly, potentially saying don't do it?

[donhector]

I was also confused by the documentation.

If you have a .env in your directory with no accompanying .envrc, you need load_dotenv = true in your direnv.toml for direnv to auto-load the .env file.

If you have both .env and .envrc, direnv will ignore the .env despite having load_dotenv = true in direnv.toml. In this case, you need to explicitly add dotenv inside your .envrc for direnv to auto-load the .env file.

That's my own experience with version 2.32.2

[Ativerc]

Please add which version of direnv added support for load_dotenv.