Document environment files

CHANGELOG.md

@@ -8,6 +8,8 @@ This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html
 
 - Arguments may now specify a `type`, which works the same way as options.
 - Boolean options may now be rewritten into strings using `rewrite`.
+- Environment variables are now automatically parsed from `.env` files.
+- Additional environment variable files can be specified with `env-file`.
 
 ### Fixed
 

docs/spec.md

@@ -674,6 +674,55 @@ It is invalid to split the configuration; if the `include` clause is used, no
 other keys can be specified in the `tusk.yml`, and the full task must be
 defined in the included file.
 
+### Environment Files
+
+Environment variables are also automatically read from a `.env` file in the
+same directory as `tusk.yml` before task execution. This file is optional by
+default, and supports typical "dotenv" extended syntax such as quotation marks,
+comments, variable substitution, and the `export` keyword.
+
+A typical file might look like this:
+
+```sh
+FOO=foovalue
+BAR=barvalue
+```
+
+Environment files can be explicitly specified as configuration at the
+top-level:
+
+```yaml
+env-file: .local.env
+```
+
+This is shorthand syntax for the following:
+
+```yaml
+env-file:
+  - path: .local.env
+    required: true
+```
+
+Multiple environment files can be specified. Entries are evaluted in order, so
+environment variables from later files override values specified in previous
+entries.
+
+Specifying any value for `env-file` will disable the default behavior of
+auto-loading an optional `.env`. To re-enable it, specify it explicitly:
+
+```yaml
+env-file:
+  - path: .env
+    required: false
+  - .local.env
+```
+
+To disable loading environment files completely, pass `[]` or `/dev/null`:
+
+```yaml
+env-file: []
+```
+
 ### Interpreter
 
 By default, any command run will default to using `sh -c` as its interpreter.

example/example.yml

@@ -1,5 +1,13 @@
 # yaml-language-server: $schema=../tusk.schema.yaml
 ---
+# Environment variables can be read from a file.
+env-file:
+  # Environment files specified as strings are automatically required.
+  - .default.env
+  # Multiple environment files or optional files may be specified as well.
+  - path: .local.env
+    required: false
+
 # Options can be defined at a global or task-specific level.
 options:
   global:

tusk.schema.json

@@ -136,6 +136,46 @@
 				}
 			]
 		},
+		"envFile": {
+			"description": "A file to load environment variables from.\nFile paths specified are relative to the configuration file.\n",
+			"oneOf": [
+				{
+					"type": "string"
+				},
+				{
+					"additionalProperties": false,
+					"properties": {
+						"path": {
+							"description": "The path to an environment file relative to the configuration file.\n",
+							"type": "string"
+						},
+						"required": {
+							"default": true,
+							"description": "Whether the file is required to exist.",
+							"type": "boolean"
+						}
+					},
+					"required": [
+						"path"
+					],
+					"type": "object"
+				}
+			]
+		},
+		"envFileClause": {
+			"description": "The files to load environment variables from.\nIf no value is specified, environment variables will be read from an optional `.env` file automatically.\n",
+			"oneOf": [
+				{
+					"$ref": "#/$defs/envFile"
+				},
+				{
+					"items": {
+						"$ref": "#/$defs/envFile"
+					},
+					"type": "array"
+				}
+			]
+		},
 		"option": {
 			"additionalProperties": false,
 			"allOf": [
@@ -560,6 +600,10 @@
 	"$schema": "http://json-schema.org/draft-07/schema#",
 	"additionalProperties": false,
 	"properties": {
+		"env-file": {
+			"$ref": "#/$defs/envFileClause",
+			"title": "env-file"
+		},
 		"interpreter": {
 			"default": "sh -c",
 			"description": "The interpreter to use for commands.\nThe interpreter is specified as an executable, which can either be an absolute path or available on the user's PATH, followed by a series of optional arguments.\nThe commands specified in individual tasks will be passed as the final argument.\n",

tusk.schema.yaml

@@ -21,6 +21,9 @@ properties:
       The usage text to display in help text when using shell aliases to create
       a custom named CLI application.
     default: the modern task runner
+  env-file:
+    title: env-file
+    $ref: "#/$defs/envFileClause"
   interpreter:
     title: interpreter
     type: string
@@ -159,6 +162,39 @@ $defs:
           - required: [command]
           - required: [value]
 
+  envFile:
+    description: >
+      A file to load environment variables from.
+
+      File paths specified are relative to the configuration file.
+    oneOf:
+      - type: string
+      - type: object
+        additionalProperties: false
+        required:
+          - path
+        properties:
+          path:
+            description: >
+              The path to an environment file relative to the configuration file.
+            type: string
+          required:
+            description: Whether the file is required to exist.
+            type: boolean
+            default: true
+
+  envFileClause:
+    description: >
+      The files to load environment variables from.
+
+      If no value is specified, environment variables will be read from an
+      optional `.env` file automatically.
+    oneOf:
+      - $ref: "#/$defs/envFile"
+      - type: array
+        items:
+          $ref: "#/$defs/envFile"
+
   type:
     description: >
       The type of the value.