Aliases

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- Add ability to set `aliases` for tasks and namespaces ([#268](https://github.com/go-task/task/pull/268), [#340](https://github.com/go-task/task/pull/340), [#879](https://github.com/go-task/task/pull/879)).
 - Improvements to Fish shell completion
   ([#897](https://github.com/go-task/task/pull/897)).
 - Added ability to set a different watch interval by setting

Taskfile.yml

@@ -2,6 +2,7 @@ version: '3'
 
 includes:
   docs:
+    aliases: [d]
     taskfile: ./docs
     dir: ./docs
 
@@ -23,6 +24,7 @@ tasks:
 
   install:
     desc: Installs Task
+    aliases: [i]
     sources:
       - './**/*.go'
     cmds:
@@ -42,6 +44,7 @@ tasks:
 
   lint:
     desc: Runs golangci-lint
+    aliases: [l]
     sources:
       - './**/*.go'
     cmds:
@@ -65,6 +68,7 @@ tasks:
 
   test:
     desc: Runs test suite
+    aliases: [t]
     deps: [install]
     cmds:
       - go test {{catLines .GO_PACKAGES}}

docs/Taskfile.yml

@@ -8,6 +8,7 @@ tasks:
 
   start:
     desc: Start website
+    aliases: [s]
     vars:
       HOST: '{{default "localhost" .HOST}}'
       PORT: '{{default "3001" .PORT}}'
@@ -25,6 +26,7 @@ tasks:
       - rm -rf ./build
 
   deploy:
-    desc: Build and deploy Docusaurus. Requires GIT_USER and GIT_PASS envs to be previous set
+    desc: Build and deploy Docusaurus
+    summary: Requires GIT_USER and GIT_PASS envs to be previous set
     cmds:
       - npx docusaurus deploy

docs/docs/api_reference.md

@@ -91,15 +91,15 @@ Some environment variables can be overriden to adjust Task behavior.
 | `dotenv` | `[]string` | | A list of `.env` file paths to be parsed. |
 | `tasks` | [`map[string]Task`](#task) | | The task definitions. |
 
-
 ### Include
 
 | Attribute | Type | Default | Description |
 | - | - | - | - |
 | `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`. |
+| `internal` | `bool` | `false` | If `true`, tasks will not be callable from the command line and will be omitted from both `--list` and `--list-all`. |
+| `aliases` | `[]string` | | Alternative names for the namespace of the included Taskfile. |
 
 :::info
 
@@ -118,11 +118,13 @@ includes:
 | - | - | - | - |
 | `desc` | `string` | | A short description of the task. This is listed when calling `task --list`. |
 | `summary` | `string` | | A longer description of the task. This is listed when calling `task --summary [task]`. |
+| `aliases` | `[]string` | | Alternative names for the task. |
+| `label` | `string` | | Overrides the name of the task in the output when a task is run. Supports variables. |
 | `sources` | `[]string` | | List of sources to check before running this task. Relevant for `checksum` and `timestamp` methods. Can be file paths or star globs. |
 | `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`. |
+| `internal` | `bool` | `false` | If `true`, this task will not be callable from the command line and will be omitted 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

@@ -230,6 +230,21 @@ includes:
       DOCKER_IMAGE: frontend_image
 ```
 
+### Namespace aliases
+
+When including a Taskfile, you can give the namespace a list of `aliases`.
+This works in the same way as [task aliases](#task-aliases) and can be used
+together to create shorter and easier-to-type commands.
+
+```yaml
+version: '3'
+
+includes:
+  generate:
+    taskfile: ./taskfiles/Generate.yml
+    aliases: [gen]
+```
+
 :::info
 
 Vars declared in the included Taskfile have preference over the
@@ -965,6 +980,30 @@ If the task does not have a summary or a description, a warning is printed.
 
 Please note: *showing the summary will not execute the command*.
 
+## Task aliases
+
+Aliases are alternative names for tasks. They can be used to make it easier and
+quicker to run tasks with long or hard-to-type names. You can use them on the
+command line, when [calling sub-tasks](#calling-another-task) in your Taskfile
+and when [including tasks](#including-other-taskfiles) with aliases from another
+Taskfile. They can also be used together with [namespace
+aliases](#namespace-aliases).
+
+```yaml
+version: '3'
+
+tasks:
+  generate:
+    aliases: [gen]
+    cmds:
+      - task: gen-mocks
+
+  generate-mocks:
+    aliases: [gen-mocks]
+    cmds:
+      - echo "generating..."
+```
+
 ## Overriding task name
 
 Sometimes you may want to override the task name printed on the summary, up-to-date

errors.go

@@ -3,6 +3,7 @@ package task
 import (
 	"errors"
 	"fmt"
+	"strings"
 
 	"mvdan.cc/sh/v3/interp"
 )
@@ -20,6 +21,15 @@ func (err *taskNotFoundError) Error() string {
 	return fmt.Sprintf(`task: Task %q not found`, err.taskName)
 }
 
+type multipleTasksWithAliasError struct {
+	aliasName string
+	taskNames []string
+}
+
+func (err *multipleTasksWithAliasError) Error() string {
+	return fmt.Sprintf(`task: Multiple tasks (%s) with alias %q found`, strings.Join(err.taskNames, ", "), err.aliasName)
+}
+
 type taskInternalError struct {
 	taskName string
 }

go.mod

@@ -9,6 +9,7 @@ require (
 	github.com/radovskyb/watcher v1.0.7
 	github.com/spf13/pflag v1.0.5
 	github.com/stretchr/testify v1.8.0
+	golang.org/x/exp v0.0.0-20220930202632-ec3f01382ef9
 	golang.org/x/sync v0.0.0-20210220032951-036812b2e83c
 	gopkg.in/yaml.v3 v3.0.1
 	mvdan.cc/sh/v3 v3.6.0-0.dev.0.20220704111049-a6e3029cd899
@@ -19,7 +20,7 @@ require (
 	github.com/mattn/go-colorable v0.1.9 // indirect
 	github.com/mattn/go-isatty v0.0.14 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
-	golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8 // indirect
+	golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f // indirect
 	golang.org/x/term v0.0.0-20210927222741-03fcf44c2211 // indirect
 	gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127 // indirect
 )

go.sum

@@ -7,7 +7,7 @@ github.com/fatih/color v1.13.0/go.mod h1:kLAiJbzzSOZDVNGyDpeOxJ47H46qBXwg5ILebYF
 github.com/frankban/quicktest v1.14.0 h1:+cqqvzZV87b4adx/5ayVOaYZ2CrvM4ejQvUdBzPPUss=
 github.com/go-task/slim-sprig v0.0.0-20210107165309-348f09dbbbc0 h1:p104kn46Q8WdvHunIJ9dAyjPVtrBPhSr3KT2yUst43I=
 github.com/go-task/slim-sprig v0.0.0-20210107165309-348f09dbbbc0/go.mod h1:fyg7847qk6SyHyPtNmDHnmrv/HOrqktSC+C9fM+CJOE=
-github.com/google/go-cmp v0.5.6 h1:BKbKCqvP6I+rmFHt06ZmyQtvB8xAkWdhFyr0ZUNZcxQ=
+github.com/google/go-cmp v0.5.8 h1:e6P7q2lk1O+qJJb4BtCQXlK8vWEO8V1ZeuEdJNOqZyg=
 github.com/joho/godotenv v1.4.0 h1:3l4+N6zfMWnkbPEXKng2o2/MR5mSwTrBih4ZEkkz1lg=
 github.com/joho/godotenv v1.4.0/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
 github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0=
@@ -34,16 +34,17 @@ github.com/stretchr/testify v1.5.1/go.mod h1:5W2xD1RspED5o8YsWQXVCued0rvSQ+mT+I5
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.0 h1:pSgiaMZlXftHpm5L7V1+rVB+AZJydKsMxsQBIJw4PKk=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+golang.org/x/exp v0.0.0-20220930202632-ec3f01382ef9 h1:RjggHMcaTVp0LOVZcW0bo8alwHrOaCrGUDgfWUHhnN4=
+golang.org/x/exp v0.0.0-20220930202632-ec3f01382ef9/go.mod h1:cyybsKvd6eL0RnXn6p/Grxp8F5bW7iYuBgsNCOHpMYE=
 golang.org/x/sync v0.0.0-20210220032951-036812b2e83c h1:5KslGYwFpkhGh+Q16bwMP3cOontH8FOep7tGV86Y7SQ=
 golang.org/x/sync v0.0.0-20210220032951-036812b2e83c/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sys v0.0.0-20200116001909-b77594299b42/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20200223170610-d5e6a3e2c0ae/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210630005230-0f9fa26af87c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8 h1:0A+M6Uqn+Eje4kHMK80dtF3JCXC4ykBgQG4Fe06QRhQ=
-golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f h1:v4INt8xihDGvnrfjMDVXGxw9wrfxYyCjk0KbXjhR55s=
+golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/term v0.0.0-20210927222741-03fcf44c2211 h1:JGgROgKl9N8DuW20oFS5gxc+lE67/N3FcwmBPMe7ArY=
 golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
-golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1 h1:go1bK/D/BFZV2I8cIQd1NKEZ+0owSTG1fDTci4IqFcE=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127 h1:qIbj1fsPNlZgppZ+VLlY7N33q108Sa+fhmuc+sWQYwY=
 gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

help.go

@@ -47,6 +47,9 @@ func (e *Executor) printTasks(listAll bool) {
 		e.Logger.FOutf(w, logger.Yellow, "* ")
 		e.Logger.FOutf(w, logger.Green, task.Task)
 		e.Logger.FOutf(w, logger.Default, ": \t%s", task.Desc)
+		if len(task.Aliases) > 0 {
+			e.Logger.FOutf(w, logger.Cyan, "\t(aliases: %s)", strings.Join(task.Aliases, ", "))
+		}
 		fmt.Fprint(w, "\n")
 	}
 	w.Flush()

internal/summary/summary.go

@@ -28,6 +28,7 @@ func PrintTask(l *logger.Logger, t *taskfile.Task) {
 	printTaskName(l, t)
 	printTaskDescribingText(t, l)
 	printTaskDependencies(l, t)
+	printTaskAliases(l, t)
 	printTaskCommands(l, t)
 }
 
@@ -61,6 +62,18 @@ func printTaskName(l *logger.Logger, t *taskfile.Task) {
 	l.Outf(logger.Default, "")
 }
 
+func printTaskAliases(l *logger.Logger, t *taskfile.Task) {
+	if len(t.Aliases) == 0 {
+		return
+	}
+	l.Outf(logger.Default, "")
+	l.Outf(logger.Default, "aliases:")
+	for _, alias := range t.Aliases {
+		l.FOutf(l.Stdout, logger.Default, " - ")
+		l.Outf(logger.Cyan, alias)
+	}
+}
+
 func hasDescription(t *taskfile.Task) bool {
 	return t.Desc != ""
 }

task.go

@@ -16,6 +16,7 @@ import (
 	"github.com/go-task/task/v3/internal/templater"
 	"github.com/go-task/task/v3/taskfile"
 
+	"golang.org/x/exp/slices"
 	"golang.org/x/sync/errgroup"
 )
 
@@ -64,16 +65,15 @@ type Executor struct {
 // Run runs Task
 func (e *Executor) Run(ctx context.Context, calls ...taskfile.Call) error {
 	// check if given tasks exist
-	for _, c := range calls {
-		t, ok := e.Taskfile.Tasks[c.Task]
-		if !ok {
-			// FIXME: move to the main package
+	for _, call := range calls {
+		task, err := e.GetTask(call)
+		if err != nil {
 			e.ListTasksWithDesc()
-			return &taskNotFoundError{taskName: c.Task}
+			return err
 		}
-		if t.Internal {
+		if task.Internal {
 			e.ListTasksWithDesc()
-			return &taskInternalError{taskName: c.Task}
+			return &taskInternalError{taskName: call.Task}
 		}
 	}
 
@@ -113,8 +113,8 @@ func (e *Executor) RunTask(ctx context.Context, call taskfile.Call) error {
 	if err != nil {
 		return err
 	}
-	if !e.Watch && atomic.AddInt32(e.taskCallCount[call.Task], 1) >= MaximumTaskCall {
-		return &MaximumTaskCallExceededError{task: call.Task}
+	if !e.Watch && atomic.AddInt32(e.taskCallCount[t.Task], 1) >= MaximumTaskCall {
+		return &MaximumTaskCallExceededError{task: t.Task}
 	}
 
 	release := e.acquireConcurrencyLimit()
@@ -331,3 +331,38 @@ func (e *Executor) startExecution(ctx context.Context, t *taskfile.Task, execute
 
 	return execute(ctx)
 }
+
+// GetTask will return the task with the name matching the given call from the taskfile.
+// If no task is found, it will search for tasks with a matching alias.
+// If multiple tasks contain the same alias or no matches are found an error is returned.
+func (e *Executor) GetTask(call taskfile.Call) (*taskfile.Task, error) {
+	// Search for a matching task
+	matchingTask, ok := e.Taskfile.Tasks[call.Task]
+	if ok {
+		return matchingTask, nil
+	}
+
+	// If didn't find one, search for a task with a matching alias
+	var aliasedTasks []string
+	for _, task := range e.Taskfile.Tasks {
+		if slices.Contains(task.Aliases, call.Task) {
+			aliasedTasks = append(aliasedTasks, task.Task)
+			matchingTask = task
+		}
+	}
+	// If we found multiple tasks
+	if len(aliasedTasks) > 1 {
+		return nil, &multipleTasksWithAliasError{
+			aliasName: call.Task,
+			taskNames: aliasedTasks,
+		}
+	}
+	// If we found no tasks
+	if len(aliasedTasks) == 0 {
+		return nil, &taskNotFoundError{
+			taskName: call.Task,
+		}
+	}
+
+	return matchingTask, nil
+}