Update docs with examples (closes #8).

README.md

@@ -27,7 +27,7 @@ There are currently four IJ subcommands (`run`, `login`, `logout`, and `rotate-l
 | -------- | ---------- | ----------- |
 | config   | f          | The path to the config file. If not supplied, `ij.yaml` and `ij.yml` are attempted in the current directory. |
 | env      | e          | Set an environment variable. Use `-e VAR=VAL` to set an explicit value for the variable `VAR`. Use `-e VAR` to use the host value of `$VAR`. |
-| env-file |            | The path to an [environment file](https://github.com/efritz/ij/blob/master/docs/environment.md#user-content-environment-file). |
+| env-file |            | The path to an [environment file](https://github.com/efritz/ij/blob/master/docs/environment.md#user-content-environment-files). |
 | no-color |            | Disable colorized output. |
 | verbose  | v          | Show debug-level output. |
 

docs/config.md

@@ -4,7 +4,7 @@ A configuration file defines tasks (units of work) and plans (configurations of
 
 | Name        | Default    | Description |
 | ----------- | ---------- | ----------- |
-| env_file    | []         | A list paths to [environment file](https://github.com/efritz/ij/blob/master/docs/environment.md#user-content-environment-file) on the host. Value may be a string or a list. |
+| env_file    | []         | A list paths to [environment file](https://github.com/efritz/ij/blob/master/docs/environment.md#user-content-environment-files) on the host. Value may be a string or a list. |
 | environment | []         | A list of environment variable definitions. Value may be a string or a list. |
 | export      | {}         | A [file list object](https://github.com/efritz/ij/blob/master/docs/config.md#user-content-file-list) describing the export phase. |
 | extends     | ''         | The path (relative/absolute on-disk, or an HTTP(S) URL) to the parent configuration. |
@@ -57,4 +57,18 @@ A file list object controls the files which move into the workspace on import an
 | exclude | []      | Glob patterns for files to be ignored during import or export. Value may be a string or a list. |
 | files   | []      | Glob patterns for files targeted for transfer during import or export. Value may be a string or a list. |
 
-Files matching a pattern in the `files` property will be *recursively* transferred in or out of the workspace. If that file also matches a pattern in the `exclude` property, it will be skipped. All symlinks are skipped during transfer. Glob patterns support `*` for optional text and `**` for multiple directories.
+Files matching a pattern in the `files` property will be *recursively* transferred in or out of the workspace. If that file also matches a pattern in the `exclude` property, it will be skipped. All symlinks are skipped during transfer. Glob patterns support `*` for optional text and `**` for multiple directories. The directories `.ij` and `.git` are implicitly blacklisted on import.
+
+```yaml
+import:
+  files:
+    - src
+    - test
+  excludes:
+    - .hg
+    - node_modules
+
+export:
+  files:
+    - '**/junit*.xml'
+```

docs/environment.md

@@ -14,6 +14,14 @@ If a variable is defined multiple times in a single environment, the last value
 - the environment exported by a previous run task
 - the command line `--environment` and `--env-file` flags
 
+The `BUILD_TIME` environment variable containing the ISO8601-formatted current UTC time is available by default. If the project directory is controlled by git, the following environment variables are also available:
+
+- *GIT_REMOTE*
+- *GIT_COMMIT*
+- *GIT_BRANCH*
+- *GIT_COMMIT_SHORT* (the first 12 chars of the commit hash)
+- *GIT_BRANCH_NORMALIZED* (non-alphanum characters replaced by a dash)
+
 # Environment Files
 
 Contents of an environment file can be interpreted as environment assignments using the `env_file` property of the config and override files, the `--env-file` command line argument, or from an `exported_environment_file` property of a run task.

docs/extend.md

@@ -16,6 +16,45 @@ A child task (with the `extends` property set) extends its parent task. If the c
 
 It is legal to form a task extend chain (*a* extends *b*, *b* extends *c*, etc), but this chain may not contain cycles.
 
+## Example
+
+This example defines the `venv-py2` and `venv-py3` tasks. Both tasks extend the same base task but update the environment so that different binary names are used by the script.
+
+```yaml
+tasks:
+  venv:
+    image: ${PY_IMAGE}
+    shell: /bin/bash
+    script: |
+      if [ ! -d ${VENV_NAME} ]; then
+        virtualenv ${VENV_NAME} --python=${VENV_PYTHON}
+      fi
+
+      source ./${VENV_NAME}/bin/activate
+      ${VENV_PIP} install -U pip
+      ls requirements* | xargs -I {} ${VENV_PIP} install -r {}
+    required_environment:
+      - VENV_NAME
+      - VENV_PYTHON
+      - VENV_PIP
+
+  venv-py2:
+    extends: venv
+    environment:
+      - VENV_NAME=venv2
+      - VENV_PYTHON=python2
+      - VENV_PIP=pip
+
+  venv-py3:
+    extends: venv
+    environment:
+      - VENV_NAME=venv3
+      - VENV_PYTHON=python3
+      - VENV_PIP=pip3
+
+# plans not shown
+```
+
 # Extending a Plan
 
 This section applies when a child and parent config both define a plan with the same name. If the plan defined in the child config does not have its `extend` property set to true, then the plan defined in the child config overwrites the plan defined in the parent config. In this section we describe the other case.
@@ -28,3 +67,46 @@ First, the environment of the child plan is appended onto the environment of the
 4. Otherwise, there is an ambiguity error and the stage cannot be inserted into the parent plan.
 
 In the first case, `before_stage` and `after_stage` must not be set in the child stage. In all cases, `before_stage` and `after_stage` must not **both** be set.
+
+## Example
+
+The parent config file in this example declares a four-stage plan for running integration tests. The parent declares only the structure of the plan and does not reference any tasks.
+
+```yaml
+# parent.yaml
+
+plans:
+  test-integration:
+    stages:
+      - name: deps
+      - name: services
+      - name: migrations
+      - name: test
+```
+
+The project config file, extending the parent config, refines the integration test plan by adding tasks to the migrations and test stages, and adds an additional stage to run fixtures.
+
+```yaml
+# ij.yaml
+
+extends: parent.yaml
+
+plans:
+  test-integration:
+    extend: true
+    stages:
+      - name: migrations
+        tasks:
+          - api-migrate-postgres
+          - api-migrate-cassandra
+        parallel: true
+      - name: fixtures
+        after_stage: migrations
+        tasks:
+          - fixtures
+      - name: test
+        tasks:
+          - test
+
+# tasks not shown
+```

docs/plans.md

@@ -33,3 +33,27 @@ If the `run mode` property is set to `on-success` (the default), then the stage
 # Metaplans
 
 A metaplan is simply a list of plans and is semantically equivalent to running the stages of the listed plans back-to-back. A metaplan can be referenced in any place that a plan can be referenced.
+
+# Example
+
+This example defines a plan with two stages. The first stage installs golang dependencies and the second stage builds three golang binaries in parallel.
+
+```yaml
+plans:
+  build:
+    stages:
+      - name: vendors
+        tasks:
+          - install-vendors
+      - name: build
+        tasks:
+          - name: go-build
+            environment: APP=a
+          - name: go-build
+            environment: APP=b
+          - name: go-build
+            environment: APP=c
+        parallel: true
+
+# tasks not shown
+```

docs/registries.md

@@ -41,3 +41,23 @@ A Google Container Registry which can be logged in via the [JSON Key File](https
 | -------- | -------- | ------- | ----------- |
 | hostname |          | gcr.io  | The GCR hostname. May also be one of `us.gcr.io`, `eu.gcr.io`, or `asia.gcr.io`. |
 | key_file | yes      |         | The path to a [service account JSON key file](https://support.google.com/cloud/answer/6158849#serviceaccounts) on the host. |
+
+# Example
+
+This example illustrates a registry list with all three registry types. It is suggested to store server registry credentials (when it is not possible to use password_file) as well as AWS credentials in the user's global override file.
+
+```yaml
+registries:
+  - server: registry.example.io
+    username: admin
+    password: secret
+
+  - type: ecr
+    access_key_id: ${AWS_ACCESS_KEY_ID}
+    secret_access_key: ${AWS_SECRET_ACCESS_KEY}
+    account_id: 641844361036
+    role: Developer
+
+  - type: gcr
+    key_file: /etc/docker-agent-keyfile.json
+```