From 111f6e7f183b843235e55bbcb3e3b759af42df4c Mon Sep 17 00:00:00 2001
From: Andrey Nering <andrey@nering.com.br>
Date: Sat, 17 Sep 2022 13:10:55 -0300
Subject: [PATCH] Add CHANGELOG entry and API documentation for #818

---
 CHANGELOG.md                             | 6 ++++++
 docs/docs/api_reference.md               | 2 ++
 docs/docs/usage.md                       | 8 ++++----
 testdata/includes_internal/Taskfile.yml  | 1 -
 testdata/includes_internal/Taskfile2.yml | 1 -
 testdata/internal_task/Taskfile.yml      | 1 -
 6 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b47ab6c2..e0b6d469 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+- Add support to marking tasks and includes as internal, which will hide them
+  from `--list` and `--list-all`
+  ([#818](https://github.com/go-task/task/pull/818)).
+
 ## v3.15.2 - 2022-09-08
 
 - Fix error when using variable in `env:` introduced in the previous release
diff --git a/docs/docs/api_reference.md b/docs/docs/api_reference.md
index 39433ef9..e67b721a 100644
--- a/docs/docs/api_reference.md
+++ b/docs/docs/api_reference.md
@@ -97,6 +97,7 @@ Some environment variables can be overriden to adjust Task behavior.
 | `taskfile` | `string` | | The path for the Taskfile or directory to be included. If a directory, Task will look for files named `Taskfile.yml` or `Taskfile.yaml` inside that directory. If a relative path, resolved relative to the directory containing the including Taskfile. |
 | `dir` | `string` | The parent Taskfile directory | The working directory of the included tasks when run. |
 | `optional` | `bool` | `false` | If `true`, no errors will be thrown if the specified file does not exist. |
+| `internal` | `bool` | `false` | If `true`, tasks will be omitted from both `--list` and `--list-all`. |
 
 :::info
 
@@ -119,6 +120,7 @@ includes:
 | `dir` | `string` | | The current directory which this task should run. |
 | `method` | `string` | `checksum` | Method used by this task. Default to the one declared globally or `checksum`. Available options: `checksum`, `timestamp` and `none` |
 | `silent` | `bool` | `false` | Skips some output for this task. Note that STDOUT and STDERR of the commands will still be redirected. |
+| `internal` | `bool` | `false` | If `true`, omit this task from both `--list` and `--list-all`. |
 | `run` | `string` | The one declared globally in the Taskfile or `always` | Specifies whether the task should run again or not if called more than once. Available options: `always`, `once` and `when_changed`. |
 | `prefix` | `string` | | Allows to override the prefix print before the STDOUT. Only relevant when using the `prefixed` output mode. |
 | `ignore_error` | `bool` | `false` | Continue execution if errors happen while executing the commands. |
diff --git a/docs/docs/usage.md b/docs/docs/usage.md
index ed2b2285..f79f10bf 100644
--- a/docs/docs/usage.md
+++ b/docs/docs/usage.md
@@ -197,8 +197,9 @@ tasks:
 ### Internal includes
 
 Includes marked as internal will set all the tasks of the included file to be
-internal as well (See the [Internal Tasks](#internal-tasks) section below). This is useful when including utility tasks that are not
-intended to be used directly by the user.
+internal as well (see the [Internal tasks](#internal-tasks) section below).
+This is useful when including utility tasks that are not intended to be used
+directly by the user.
 
 ```yaml
 version: '3'
@@ -238,7 +239,7 @@ use the [default function](https://go-task.github.io/slim-sprig/defaults.html):
 
 :::
 
-## Internal Tasks
+## Internal tasks
 
 Internal tasks are tasks that cannot be called directly by the user. They will
 not appear in the output when running `task --list|--list-all`. Other tasks may
@@ -249,7 +250,6 @@ function-like tasks that have no useful purpose on the command line.
 version: '3'
 
 tasks:
-
   build-image-1:
     cmds:
       - task: build-image
diff --git a/testdata/includes_internal/Taskfile.yml b/testdata/includes_internal/Taskfile.yml
index 64121323..f6c32167 100644
--- a/testdata/includes_internal/Taskfile.yml
+++ b/testdata/includes_internal/Taskfile.yml
@@ -6,7 +6,6 @@ includes:
     internal: true
 
 tasks:
-
   task-1:
     cmds:
       - task: included:default
diff --git a/testdata/includes_internal/Taskfile2.yml b/testdata/includes_internal/Taskfile2.yml
index dce136f0..61869afe 100644
--- a/testdata/includes_internal/Taskfile2.yml
+++ b/testdata/includes_internal/Taskfile2.yml
@@ -1,7 +1,6 @@
 version: '3'
 
 tasks:
-
   task-3:
     cmds:
       - echo "Hello, World!"
diff --git a/testdata/internal_task/Taskfile.yml b/testdata/internal_task/Taskfile.yml
index 8317cdaa..992cdb70 100644
--- a/testdata/internal_task/Taskfile.yml
+++ b/testdata/internal_task/Taskfile.yml
@@ -1,7 +1,6 @@
 version: '3'
 
 tasks:
-
   task-1:
     cmds:
       - task: task-3