From f519f56078c35a8e2c9ac749b0fb12630fd48993 Mon Sep 17 00:00:00 2001
From: Andrey Nering <andrey.nering@gmail.com>
Date: Sat, 13 Oct 2018 18:14:42 -0300
Subject: [PATCH] Add documentation for including other Taskfiles

---
 docs/usage.md | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/docs/usage.md b/docs/usage.md
index 1c5087cc..2bc75067 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -48,7 +48,7 @@ tasks:
       hallo: welt
 ```
 
-## OS specific task
+## Operating System specific tasks
 
 If you add a `Taskfile_{{GOOS}}.yml` you can override or amend your Taskfile
 based on the operating system.
@@ -86,6 +86,31 @@ It's also possible to have an OS specific `Taskvars.yml` file, like
 `Taskvars_windows.yml`, `Taskfile_linux.yml`, or `Taskvars_darwin.yml`. See the
 [variables section](#variables) below.
 
+## Including other Taskfiles
+
+If you want to share tasks between different projects (Taskfiles), you can use
+the importing mechanism to include other Taskfiles using the `includes` keyword:
+
+```yaml
+version: '2'
+
+includes:
+  docs: ./documentation # will look for ./documentation/Taskfile.yml
+  docker: ./DockerTasks.yml
+```
+
+The tasks described in the given Taskfiles will be available with the informed
+namespace. So, you'd call `task docs:serve` to run the `serve` task from
+`documentation/Taskfile.yml` or `task docker:build` to run the `build` task
+from the `DockerTasks.yml` file.
+
+> The included Taskfiles must be using the same schema version the main
+> Taskfile uses.
+
+> Also, for now included Taskfiles can't include other Taskfiles.
+> This was a deliberate decision to keep use and implementation simple.
+> If you disagree, open an GitHub issue and explain your use case. =)
+
 ## Task directory
 
 By default, tasks will be executed in the directory where the Taskfile is