SubTaskfiles

[johanvo]

What

• adapt task:help in the Taskfile-generator template so it can accept a filename as parameter $1 (it defaults to $0, consistent with previous behavior)
• added documentation explaining the uses for SubTaskfiles

Why

By documenting ways to expand upon the base Taskfile concept (for advanced use-cases) we promote a consistent ecosystem and build upon shared experience, making Taskfiles more useful for everyone.

Specifically: in cases where you have groups of tasks that are only useful in certain contexts, SubTaskfiles allow you to keep them logically grouped with a minimum of overhead, no weird syntax and all the general niceties of a regular Taskfile (its-just-bash, simple help output, access to general usability functions, etc.

Example of minimal SubTaskfile setup

Relevant parts of ./Taskfile

#!/usr/bin/env bash

function task:foo { ## Call SubTaskfile
	SUBTASKFILE_DIR="./path/to/subtaskfile/"

	source "$SUBTASKFILE_DIR/SubTaskfile"

	task:"${@-_help}"
}

task:${@-help}

---

Full contents of ./path/to/subtaskfile/SubTaskfile

#!/usr/bin/env bash

function task:bar { ## Example function in SubTaskfile
	printf "foobar"
}

# Without this, you cannot run `./Taskfile foo` or `./Taskfile foo help`
function task:_help { ## Show all available tasks
	task:help "$SUBTASKFILE_DIR/SubTaskfile"
}

ToDo

• finish PR description
• discuss splitting up About page into general explanation and "advanced topics", including autocompletion

[rick-nu]

Hey @johanvo. First off all, hats off! 🚀 This looks like a GREAT addition! I have some small findings to improve this even further, let's discuss them IRL. I'm dropping them here in the PR FYI and to write out my thoughts.

[rick-nu]

So I have the following output now for ./Taskfile:

❯ ./Taskfile

<banner>

=> Available tasks

Home Assistant OS
  haos                       List all Home Assistant OS related tasks

Usage: /home/rick/Projects/FuturePortal/Server/Taskfile <task> <args>

When I run ./Taskfile haos:

❯ ./Taskfile haos

<banner>

=> Available server tasks

Home Assistant OS
  start                      Start the VM
  restart                    Restart the VM
  shell                      Open Home Assistant OS shell
  shutdown                   Stop the VM gracefully
  status                     Show the status of the virtual machines
Home Assistant OS backup
  backup                     Create a backup of the Home Assistant OS VM
Home Assistant OS installation
  create                     Create the Home Assistant OS VM
  auto-start                 Enable auto-start for the VM
  edit                       Edit the Home Assistant OS VM configuration
  remove                     Remove the Home Assistant OS VM and disk image

Usage: ./home-assistant-os/SubTaskfile <task> <args>

What I would love to see, and that might clarify a lot for the user:

❯ ./Taskfile haos

<banner>

=> Available server tasks

Home Assistant OS
  haos start                      Start the VM
  haos restart                    Restart the VM
  haos shell                      Open Home Assistant OS shell
  haos shutdown                   Stop the VM gracefully
  haos status                     Show the status of the virtual machines
Home Assistant OS backup
  haos backup                     Create a backup of the Home Assistant OS VM
Home Assistant OS installation
  haos create                     Create the Home Assistant OS VM
  haos auto-start                 Enable auto-start for the VM
  haos edit                       Edit the Home Assistant OS VM configuration
  haos remove                     Remove the Home Assistant OS VM and disk image

Usage: ./Taskfile ${YELLOW}haos <task>${RESET} <args>

Or maybe something like a header:

❯ ./Taskfle haos

<banner>

=> Showing sub-tasks for ${YELLOW}haos${RESET}

Home Assistant OS
  start                      Start the VM
  restart                    Restart the VM
  shell                      Open Home Assistant OS shell
  shutdown                   Stop the VM gracefully
  status                     Show the status of the virtual machines
Home Assistant OS backup
  backup                     Create a backup of the Home Assistant OS VM
Home Assistant OS installation
  create                     Create the Home Assistant OS VM
  auto-start                 Enable auto-start for the VM
  edit                       Edit the Home Assistant OS VM configuration
  remove                     Remove the Home Assistant OS VM and disk image

Usage: ./Taskfile ${YELLOW}haos <task>${RESET} <args>

The current output is not clear enough to me

[rick-nu]

Suggested change

	# Without this, you cannot run `./Taskfile foo` or `./Taskfile foo help`
	function task:_help { ## Show all available tasks
	# =========================================================
	# SubTaskfile helper
	# =========================================================
	function task:_help { # Show all available tasks

[rick-nu]

I would love to see a generator option - [ ] Include SubTaskfile that gives you an example of a SubTaskfile ready for you to copy over