Detail environment variables usage in README.md

[kenden]

Why the change

The section Environment Variables in the README only provides information about passing environment variables to the recipes.
Finding the information about how to create just variables from the shell environment variables can be difficult.

What's the change

The "Environment Variables" section now adds 2 subsections:

• How to pass environment variables to recipes
• Loading just variables from the shell environments variables

Additionally, the subsection "How to pass environment variables to recipes"
now includes information about the export setting, using dotenv, and the dotenv-load setting.

[casey]

Nice, these are good additions. I added some comments regarding wording and formatting.

[casey]

Suggested change

	`just` will load environment variables from a file named `.env` if the setting [dotenv-load](https://github.com/casey/just#dotenv-load) is present. This file can be located in the same directory as your justfile or in a parent directory. These variables are environment variables, not `just` variables, and so must be accessed using `$VARIABLE_NAME` in recipes and backticks.
	`just` will load environment variables from a file named `.env` if [dotenv-load](https://github.com/casey/just#dotenv-load) is set. This file can be located in the same directory as your justfile or in a parent directory. These variables are environment variables, not `just` variables, and so must be accessed using `$VARIABLE_NAME` in recipes and backticks.

[kenden]

Thanks, updated

[casey]

Suggested change

	===== Exporting `just` variables
	==== Exporting `just` Variables

[kenden]

Thanks, I updated

[casey]

I think this section is probably unnecessary

Suggested change

	==== How to pass environment variables to recipes
	There are two ways to pass environment variables to recipes: exporting `just` variables, or using an `.env` file.

[kenden]

I removed it

[casey]

Suggested change

	Note: the setting link:README.adoc#export[export] causes all `just` variables to be exported to recipes as enviroment variables.
	When link:README.adoc#export[export] is set, all `just` variables are exported as environment variables.

[kenden]

Thanks, I updated

[casey]

Suggested change

	===== Using an `.env` file
	`just` can load an .env file if the setting link:README.adoc#dotenv-load[dotenv-load] is present. The variables in the file will be available as environment variables to the recipes. See link:README.adoc#dotenv-integration[here] for more information.
	==== Loading Environment Variables from a `.env` File
	`just` will load environment variables from a `.env` file if link:README.adoc#dotenv-load[dotenv-load] is set. The variables in the file will be available as environment variables to the recipes. See link:README.adoc#dotenv-integration[dotenv-integration] for more information.

[kenden]

Thanks, I updated

[casey]

I think that second part is redundant, because if they're loaded using env_var, they will already be exported to recipes by default.

Suggested change

	==== Loading `just` variables from the shell environments variables
	Environment variables from the shell can be loaded as variables in `just` with the functions `env_var()` and `en_var_or_default()`, described link:README.adoc#environment-variables[here].
	They could then be exported to the recipes using link:README.adoc#exporting-just-variables[export].
	==== Setting `just` Variables from Environments Variables
	Environment variables can propagated to `just` variables using the functions `env_var()` and `env_var_or_default()`. See link:README.adoc#environment-variables[environment-variables].

[qnerden]

Oh really? Then I would add that detail, and also in #environment variable functions sections.

[kenden]

edited

[casey]

The readme was recently converted from asciidoctor to markdown, so there'll be some merge conflicts to resolve. Sorry for the hassle!

[kenden]

The readme was recently converted from asciidoctor to markdown, so there'll be some merge conflicts to resolve. Sorry for the hassle!

And I learned adoc formatting just for this :)
Thanks for the comments; I will wait for #1093 to be merged to update the PR.

[kenden]

There are two sections called "Environment Variables". Maybe we could rename

Environment Variables

(after Setting Variables from the Command Line)
to something different, like "Getting and exporting environment variables") ?

[casey]

Ah, right, so linking doesn't work? How about "Getting and Setting Environment Variables" as the header for the section that starts with "Assignments prefixed with the export keyword…"?

[kenden]

Linking worked, but it is a bit harder to navigate in the table of content. I edited as you proposed

[casey]

Thanks for updating this! A couple of comments.

[casey]

I think this section if potentially confusing. If an environment variable is set, it will be available to recipes, but you don't have to call env_var for that to be the case.

Suggested change

	- `env_var(key)` — Retrieves the environment variable with name `key`, aborting if it is not present. It will be available as environment variable to the recipes.
	```make
	HELLO := env_var('HELLO')
	test:
	echo "${HELLO}"
	```
	- `env_var(key)` — Retrieves the environment variable with name `key`, aborting if it is not present.

[kenden]

Hue. Indeed. I was convinced that environment variables (from the shell) were /not/ available to recipes.
So
my_var := env_var('TEST')
is just the same as

my_var := `echo ${TEST}`

I edited the example and removed the confusing text

[casey]

Suggested change

	- `env_var_or_default(key, default)` — Retrieves the environment variable with name `key`, returning `default` if it is not present. It will be available as environment variable to the recipes.
	- `env_var_or_default(key, default)` — Retrieves the environment variable with name `key`, returning `default` if it is not present.

[kenden]

edited

[casey]

Code blocks with make syntax are extracted and parsed, to make sure that they're correct syntax, so the test is failing when it reaches /home/user. This should be wrapped in a separate code block of type sh.

[kenden]

Thanks! Fixed.

[casey]

Nice, merged!