Add CHANGELOG entry and API documentation for #818

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

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. |

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
+internal as well (see the [Internal tasks](#internal-tasks) section below).
-intended to be used directly by the user.
+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

testdata/includes_internal/Taskfile.yml

@@ -6,7 +6,6 @@ includes:
     internal: true
 
 tasks:
-
   task-1:
     cmds:
       - task: included:default

testdata/includes_internal/Taskfile2.yml

@@ -1,7 +1,6 @@
 version: '3'
 
 tasks:
-
   task-3:
     cmds:
       - echo "Hello, World!"

testdata/internal_task/Taskfile.yml

@@ -1,7 +1,6 @@
 version: '3'
 
 tasks:
-
   task-1:
     cmds:
       - task: task-3