From 5b26f156d85c2526bb58799b158358200721bce6 Mon Sep 17 00:00:00 2001
From: Hein Thant Maung Maung <me@heinthanth.com>
Date: Mon, 16 May 2022 10:36:28 +0630
Subject: [PATCH] update docs and fix critical error in bundled js

---
 .gitattributes  |  1 +
 README.md       | 83 +++++++++++++++++++++++++++++++++++++++++++++++--
 example.xuerun  |  2 +-
 src/core.coffee |  7 +++--
 4 files changed, 88 insertions(+), 5 deletions(-)
 create mode 100644 .gitattributes

diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..6266fae
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1 @@
+*.xuerun linguist-language=YAML
\ No newline at end of file
diff --git a/README.md b/README.md
index fc697ae..b63452e 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,53 @@ And move it to ur path. Eg. `/usr/bin`, `/usr/local/bin`, etc. For windows, the
 
 ## Configurations
 
-Complete Configurations Example:
+General usage is:
+
+```text
+xuerun [tasks]... [options]...
+```
+
+TL;DR
+
+```shell
+$ xuerun                      # will execute 'all' task if exist
+$ xuerun task-name-to-execute # will execute 'task-name-to-execute'
+$ xuerun -t some-tasks-path   # will look for task in 'some-tasks-path'
+$ xuerun -n some-task         # will print commands to run ( won't execute )
+```
+
+### Tasks Path ( `--tasks, -t` option )
+
+Unless `--tasks ( -t )` is given, XueRun will look for `tasks.xuerun`. If `tasks.xuerun` exists, XueRun will use that.
+
+```shell
+$ xuerun someName # xuerun will look for someName in tasks.xuerun
+$ xuerun -t example.xuerun someName # xuerun will look for someName in example.xuerun
+```
+
+### Task Name ( `[tasks]` )
+
+Unless task names are given, XueRun will look for a task named `all`. If `all` task exists, XueRun will execute that.
+
+```shell
+$ xuerun task-name-to-execute
+```
+
+You can give multiple task name too.
+
+```shell
+$ xuerun taskOne taskTwo taskThree # these tasks will run in sequantial order.
+```
+
+### Recon ( `--recon, -n` option )
+
+Use `--recon ( -n )` to emulate task execution ( but won't work in some edge cases ).
+
+```shell
+$ xuerun -n some-task # xuerun will print commands instead of executing
+```
+
+### Complete Configurations Example
 
 ```yaml
 dependOnMeToo:
@@ -20,7 +66,7 @@ dependOnMeToo:
     when: opt.release # if opt.release is true
   - cmd: echo "Since passParentOptions is true in 'dependOnMe' task"
     when: opt.release # if opt.release is true
-  passEnv: [ PATH ] # u need to pass env to use ur PATH.
+  passEnv: [ PATH ] # u need to pass env to use ur PATH. Pass true to pass all environment variables
 dependOnMe:
   description: some task
   # cwd: / # try change cwd and see {{ Deno.cwd() }} output!
@@ -48,6 +94,38 @@ taskName:
 
 I think this example show u a lot! Have Fun xuerunning!
 
+## Some Notes
+
+Here's some notes to be considered.
+
+### Option passing
+
+If u specified `passEnv` and `passCLI`, given env and CLI arguments will be passed to `opt` object and can be used with `{{}}`
+
+
+
+### When Option ( WARNING )
+
+This `taskName > command > subcommand > when` ( when ) expression is evaluated using `eval` function from javascript and can inject raw JS codes. So, use at ur own risk.
+
+```yaml
+- cmd: echo "Don't run me unless status is 'true'"
+  when: opt.status == 'true'
+```
+
+### JS Expression
+
+You can use `{{ expression }}` in commands, options, etc. XueRun use `eta` to render those. string templates. Keep in mind, raw JS code can be injected too. So, use at ur own risk.
+
+```yaml
+command:
+- cmd: echo "it's PATH env => {{ opt.PATH }}  and CLI release option => {{ opt.release }}"
+passEnv: [ PATH ]
+passCLI: true
+```
+
+Then, when u run with `xuerun taskName --release`, `opt.PATH` will be replaced with ur PATH env and `opt.release` will be replaced with `true`.
+
 ## How to Build
 
 First, clone this repo. Then, run "tools/bootstrap.ts"
@@ -59,3 +137,4 @@ deno run tools/bootstrap.ts
 ## License
 
 XueRun is licensed under BSD-2-Clause. For more, see [LICENSE](LICENSE).
+ 
\ No newline at end of file
diff --git a/example.xuerun b/example.xuerun
index ea3e641..42e36c0 100644
--- a/example.xuerun
+++ b/example.xuerun
@@ -6,7 +6,7 @@ dependOnMeToo:
     when: opt.release # if opt.release is true
   - cmd: echo "Since passParentOptions is true in 'dependOnMe' task"
     when: opt.release # if opt.release is true
-  passEnv: [ PATH ] # u need to pass env to use ur PATH.
+  passEnv: [ PATH ] # u need to pass env to use ur PATH. Pass true to pass all environment variables
 dependOnMe:
   description: some task
   # cwd: / # try change cwd and see {{ Deno.cwd() }} output!
diff --git a/src/core.coffee b/src/core.coffee
index 84916f5..b4a543c 100644
--- a/src/core.coffee
+++ b/src/core.coffee
@@ -76,9 +76,12 @@ export runRecipe = (rc, recipe, options, recon, asIngredient) ->
             Deno.exit(1)
 
         # used by eval
-        opt = currentOption
+        globalThis.opt = currentOption
         # don't run if eval when is false
-        if typeof cmdOption == "object" and not Boolean(eval(cmdOption.when)) then continue
+        if typeof cmdOption == "object" and not Boolean(eval(cmdOption.when))
+            continue
+        # I don't need here
+        delete globalThis.opt
 
         commandToRun = [
             (if typeof cmdOption == "object" and