Detail environment variables usage in README.md #1086

kenden · 2022-02-04T13:37:47Z

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 · 2022-02-04T19:22:15Z

README.adoc

@@ -936,7 +936,7 @@ The executable is at: /bin/just

 ==== Dotenv Integration

-`just` will load environment variables from a file named `.env`. 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 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.


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.

Thanks, updated

casey · 2022-02-05T00:45:53Z

README.adoc

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


Suggested change

===== Exporting `just` variables

==== Exporting `just` Variables

Thanks, I updated

casey · 2022-02-05T00:46:12Z

README.adoc

+==== 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.
+


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.

I removed it

casey · 2022-02-05T00:47:50Z

README.adoc

@@ -1158,6 +1164,17 @@ a $A $B=`echo $A`:
  echo $A $B
 ```

+Note: the setting link:README.adoc#export[export] causes all `just` variables to be exported to recipes as enviroment variables.


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.

Thanks, I updated

casey · 2022-02-05T00:49:17Z

README.adoc

+===== 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.


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.

Thanks, I updated

casey · 2022-02-05T00:51:44Z

README.adoc

+==== 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].


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].

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

casey · 2022-02-07T00:21:01Z

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

kenden · 2022-02-08T11:43:41Z

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.

Signed-off-by: kenden <kenden@gmail.com>

dotenv-load is just set. Not 'to true' Signed-off-by: kenden <kenden@gmail.com>

Signed-off-by: kenden <kenden@gmail.com>

kenden · 2022-02-23T18:45:22Z

README.md

+#### Setting `just` Variables from Environments Variables
+
+Environment variables can be propagated to `just` variables using the functions `env_var()` and `env_var_or_default()`. These variables will be available as environment variables to the recipes.
+See [environment-variables](#environment-variables).


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") ?

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…"?

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 · 2022-02-23T20:54:19Z

README.md

+- `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}"
+```
+


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.

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 · 2022-02-23T20:54:34Z

README.md

+  echo "${HELLO}"
+```
+
+- `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.


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.

also: remove confusing parts Signed-off-by: kenden <kenden@gmail.com>

README.md

casey · 2022-02-24T00:40:50Z

README.md

@@ -899,6 +899,16 @@ This is an x86_64 machine

 - `env_var(key)` — Retrieves the environment variable with name `key`, aborting if it is not present.

+```make


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.

Thanks! Fixed.

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. Signed-off-by: kenden <kenden@gmail.com>

casey · 2022-02-24T09:14:30Z

Nice, merged!

kenden force-pushed the detail_envvar_docs branch from ad1d2e1 to 8474387 Compare February 4, 2022 13:42

kenden changed the title ~~Detail environment variable usage in README.adoc~~ Detail environment variables usage in README.adoc Feb 4, 2022

casey requested changes Feb 5, 2022

View reviewed changes

Updates after comments and markdown update

23ec017

Signed-off-by: kenden <kenden@gmail.com>

kenden force-pushed the detail_envvar_docs branch from 8474387 to 23ec017 Compare February 23, 2022 17:03

kenden changed the title ~~Detail environment variables usage in README.adoc~~ Detail environment variables usage in README.md Feb 23, 2022

kenden added 3 commits February 23, 2022 19:33

Remove duplicated section, fixing CI fail

6db6d50

Signed-off-by: kenden <kenden@gmail.com>

Fix for dotenv-load is to "true"

7ccc7e2

dotenv-load is just set. Not 'to true' Signed-off-by: kenden <kenden@gmail.com>

Fix title section

10bb002

Signed-off-by: kenden <kenden@gmail.com>

kenden commented Feb 23, 2022

View reviewed changes

casey requested changes Feb 23, 2022

View reviewed changes

Add section get envvar from env

daab432

also: remove confusing parts Signed-off-by: kenden <kenden@gmail.com>

kenden commented Feb 23, 2022

View reviewed changes

README.md Outdated Show resolved Hide resolved

casey reviewed Feb 24, 2022

View reviewed changes

kenden and others added 2 commits February 24, 2022 10:10

Fix example

b5cc45e

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. Signed-off-by: kenden <kenden@gmail.com>

Merge branch 'master' into detail_envvar_docs

1b62dbd

casey merged commit 88922b8 into casey:master Feb 24, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Detail environment variables usage in README.md #1086

Detail environment variables usage in README.md #1086

kenden commented Feb 4, 2022 •

edited

Loading

casey left a comment

casey Feb 4, 2022

kenden Feb 23, 2022

casey Feb 5, 2022

kenden Feb 23, 2022

casey Feb 5, 2022

kenden Feb 23, 2022

casey Feb 5, 2022

kenden Feb 23, 2022

casey Feb 5, 2022

kenden Feb 23, 2022

casey Feb 5, 2022

qnerden Feb 23, 2022 •

edited

Loading

kenden Feb 23, 2022

casey commented Feb 7, 2022

kenden commented Feb 8, 2022

kenden Feb 23, 2022

casey Feb 23, 2022

kenden Feb 23, 2022 •

edited

Loading

casey left a comment

casey Feb 23, 2022

kenden Feb 23, 2022

casey Feb 23, 2022

kenden Feb 23, 2022

casey Feb 24, 2022

kenden Feb 24, 2022

casey commented Feb 24, 2022

	`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.


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

		===== Exporting `just` variables

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

		==== 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.

	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.

		===== 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.

	- `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.

		@@ -899,6 +899,16 @@ This is an x86_64 machine

		- `env_var(key)` — Retrieves the environment variable with name `key`, aborting if it is not present.

		```make

Detail environment variables usage in README.md #1086

Detail environment variables usage in README.md #1086

Conversation

kenden commented Feb 4, 2022 • edited Loading

Why the change

What's the change

casey left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

qnerden Feb 23, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

casey commented Feb 7, 2022

kenden commented Feb 8, 2022

Choose a reason for hiding this comment

Environment Variables

Choose a reason for hiding this comment

kenden Feb 23, 2022 • edited Loading

Choose a reason for hiding this comment

casey left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

casey commented Feb 24, 2022

kenden commented Feb 4, 2022 •

edited

Loading

qnerden Feb 23, 2022 •

edited

Loading

kenden Feb 23, 2022 •

edited

Loading