From 0deb2d78fb3b7833dd39d62dcebf8632b5e1da58 Mon Sep 17 00:00:00 2001
From: Andrey Nering <andrey.nering@gmail.com>
Date: Wed, 5 Jul 2017 21:31:41 -0300
Subject: [PATCH] improve README documentation

---
 README.md | 76 ++++++++++++++++++++++++++++---------------------------
 1 file changed, 39 insertions(+), 37 deletions(-)

diff --git a/README.md b/README.md
index 9f18691f..41088154 100644
--- a/README.md
+++ b/README.md
@@ -148,6 +148,9 @@ css:
     - npm run buildcss
 ```
 
+If there are more than one dependency, they always run in parallel for better
+performance.
+
 Each task can only be run once. If it is included from another dependend task causing
 a cyclomatic dependency, execution will be stopped.
 
@@ -268,55 +271,52 @@ up-to-date.
 
 ### Variables
 
-```yml
-build:
-  deps: [setvar]
-  cmds:
-    - echo "{{.PREFIX}} {{.THEVAR}}"
-  vars:
-    PREFIX: "Path:"
+When doing interpolation of variables, Task will look for the below.
+They are listed below in order of importance (e.g. most important first):
 
-setvar:
-  cmds:
-    - echo "{{.PATH}}"
-  set: THEVAR
+- Variables given while calling a task from another.
+  (See [Calling another task](#calling-another-task) above)
+- Environment variables
+- Variables available in the `Taskvars.yml` file
+- Variables declared locally in the task
+
+Example of overriding with environment variables:
+
+```bash
+$ TASK_VARIABLE=a-value task do-something
 ```
 
-The above sample saves the path into a new variable which is then again echoed.
+Example of `Taskvars.yml` file:
 
-You can use environment variables, task level variables and a file called
-`Taskvars.yml` as source of variables.
+```yml
+PROJECT_NAME: My Project
+DEV_MODE: production
+GIT_COMMIT: $git log -n 1 --format=%h
+```
 
-They are evaluated in the following order:
+Example of locally declared vars:
 
-Task local variables are overwritten by variables found in `Taskvars` file.
-Variables found in `Taskvars` file are overwritten with variables from the
-environment. The output of the last command is stored in the environment. So
-you can do something like this:
+```yml
+print-var:
+  cmds:
+    echo "{{.VAR}}"
+  vars:
+    VAR: Hello!
+```
+
+> NOTE: It's also possible setting a variable globally using `set` attribute
+in task, but this is deprecated:
 
 ```yml
 build:
-  deps: [setvar]
+  deps: [set-message]
   cmds:
-    - echo "{{.PREFIX}} '{{.THEVAR}}'"
-  vars:
-    PREFIX: "Result: "
+    - echo "Message: {{.MESSAGE}}"
 
-setvar:
+set-message:
   cmds:
-    - echo -n "a"
-    - echo -n "{{.THEVAR}}b"
-    - echo -n "{{.THEVAR}}c"
-  set: THEVAR
-```
-
-The result of a run of build would be:
-
-```
-a
-ab
-abc
-Result:  'abc'
+    - echo "This is an important message"
+  set: MESSAGE
 ```
 
 #### Dynamic variables
@@ -333,6 +333,8 @@ build:
     LAST_GIT_COMMIT: $git log -n 1 --format=%h
 ```
 
+This works for all types of variables.
+
 ### Go's template engine
 
 Task parse commands as [Go's template engine][gotemplate] before executing