From 968041ff196b2c701cc734f7115dec5704d4f64c Mon Sep 17 00:00:00 2001
From: Andrey Nering <andrey@nering.com.br>
Date: Wed, 1 Mar 2023 22:46:53 -0300
Subject: [PATCH] Add `--global` (`-g`) flag

This will run a Taskfile from the home directory, i.e., `$HOME/Taskfile.yml`.
---
 CHANGELOG.md               |  4 ++++
 cmd/task/task.go           | 15 +++++++++++++++
 docs/docs/api_reference.md |  1 +
 docs/docs/usage.md         | 34 ++++++++++++++++++++++++++++++++++
 4 files changed, 54 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e73cd26db6..79ea82a744 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+- Add a brand new `--global` (`-g`) flag that will run a Taskfile from your
+  `$HOME` directory. This is useful to have automation that you can run from
+  anywhere in your system!
+  ([Documentation](https://taskfile.dev/usage/#running-a-global-taskfile), [#1029](https://github.com/go-task/task/pull/1029) by @andreynering).
 - Add ability to set `error_only: true` on the `group` output mode. This will
   instruct Task to only print a command output if it returned with a non-zero
   exit code
diff --git a/cmd/task/task.go b/cmd/task/task.go
index 1f4eba9a42..89d9ed8a11 100644
--- a/cmd/task/task.go
+++ b/cmd/task/task.go
@@ -72,6 +72,7 @@ func main() {
 		output      taskfile.Output
 		color       bool
 		interval    time.Duration
+		global      bool
 	)
 
 	pflag.BoolVar(&versionFlag, "version", false, "show Task version")
@@ -98,6 +99,7 @@ func main() {
 	pflag.BoolVarP(&color, "color", "c", true, "colored output. Enabled by default. Set flag to false or use NO_COLOR=1 to disable")
 	pflag.IntVarP(&concurrency, "concurrency", "C", 0, "limit number tasks to run concurrently")
 	pflag.DurationVarP(&interval, "interval", "I", 0, "interval to watch for changes")
+	pflag.BoolVarP(&global, "global", "g", false, "runs global Taskfile, from $HOME/Taskfile.{yml,yaml}")
 	pflag.Parse()
 
 	if versionFlag {
@@ -121,6 +123,19 @@ func main() {
 		return
 	}
 
+	if global && dir != "" {
+		log.Fatal("task: You can't set both --global and --dir")
+		return
+	}
+	if global {
+		home, err := os.UserHomeDir()
+		if err != nil {
+			log.Fatal("task: failed to get user home directory: %w", err)
+			return
+		}
+		dir = home
+	}
+
 	if dir != "" && entrypoint != "" {
 		log.Fatal("task: You can't set both --dir and --taskfile")
 		return
diff --git a/docs/docs/api_reference.md b/docs/docs/api_reference.md
index a47d325320..9c65a6d3c2 100644
--- a/docs/docs/api_reference.md
+++ b/docs/docs/api_reference.md
@@ -28,6 +28,7 @@ variable
 | `-n` | `--dry` | `bool` | `false` | Compiles and prints tasks in the order that they would be run, without executing them. |
 | `-x` | `--exit-code` | `bool` | `false` | Pass-through the exit code of the task command. |
 | `-f` | `--force` | `bool` | `false` | Forces execution even when the task is up-to-date. |
+| `-g` | `--global` | `bool` | `false` | Runs global Taskfile, from `$HOME/Taskfile.{yml,yaml}`. |
 | `-h` | `--help` | `bool` | `false` | Shows Task usage. |
 | `-i` | `--init` | `bool` | `false` | Creates a new Taskfile.yaml in the current folder. |
 | `-I` | `--interval` | `string` | `5s` | Sets a different watch interval when using `--watch`, the default being 5 seconds. This string should be a valid [Go Duration](https://pkg.go.dev/time#ParseDuration). |
diff --git a/docs/docs/usage.md b/docs/docs/usage.md
index 0e8f162fde..cf8cb1f6f9 100644
--- a/docs/docs/usage.md
+++ b/docs/docs/usage.md
@@ -81,6 +81,40 @@ In this example, we can run `cd <service>` and `task up` and as long as the
 `<service>` directory contains a `docker-compose.yml`, the Docker composition will be
 brought up.
 
+### Running a global Taskfile
+
+If you call Task with the `--global` (alias `-g`) flag, it will look for your
+home directory instead of your working directory. In short, Task will look for
+a Taskfile on either `$HOME/Taskfile.yml` or `$HOME/Taskfile.yaml` paths.
+
+This is useful to have automation that you can run from anywhere in your
+system!
+
+:::info
+
+When running your global Taskfile with `-g`, tasks will run on `$HOME` by
+default, and not on your working directory!
+
+As mentioned in the previous section, the `{{.USER_WORKING_DIR}}` special
+variable can be very handy here to run stuff on the directory you're calling
+`task -g` from.
+
+```yaml
+version: '3'
+
+tasks:
+  from-home:
+    cmds:
+      - pwd
+
+  from-working-directory:
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - pwd
+```
+
+:::
+
 ## Environment variables
 
 ### Task