Skip to main content

Run a task

1 min

Even though we've created a task, it's not useful unless we run it, which is done with the moon run <target> command. This command requires a single argument, a primary target, which is the pairing of a project name and task name. In the example below, our project is app, the task is typecheck, and the target is app:typecheck.

$ moon run app:typecheck

When this command is ran, it will do the following:

  • Generate a directed acyclic graph, known as the dependency graph.
  • Insert deps as targets into the graph.
  • Insert the primary target into the graph.
  • Run all tasks in the graph in parallel and in topological order (the dependency chain).
  • For each task, calculate hashes and either:
    • On cache hit, exit early and return the last run.
    • On cache miss, run the task and generate a new cache.

Running dependents

moon will always run upstream dependencies (deps) before running the primary target, as their outputs may be required for the primary target to function correctly.

However, if you're working on a project that is shared and consumed by other projects, you may want to verify that downstream dependents have not been indirectly broken by any changes. This can be achieved by passing the --dependents option, which will run dependent targets (of the same task name) after the primary target.

$ moon run app:typecheck --dependents

Running based on affected files only

By default moon run will always run the target, regardless if files have actually changed. However, this is typically fine because of our smart hashing & cache layer. With that being said, if you'd like to only run a target if files have changed, pass the --affected flag.

$ moon run app:typecheck --affected

Under the hood, we extract locally touched (created, modified, staged, etc) files from your configured VCS, and exit early if no files intersect with the task's inputs.

Using upstream changes

If you'd like to determine affected files based on upstream changes instead of local changes, pass the --upstream flag. This will extract touched files by comparing the current HEAD against the vcs.defaultBranch.

$ moon run app:typecheck --affected --upstream

Filtering based on change status

We can take this a step further by filtering down affected files based on a change status, using the --status option. This option accepts the following values: added, deleted, modified, staged, unstaged, untracked. If not provided, the option defaults to all.

$ moon run app:typecheck --affected --status deleted

Passing arguments to the underlying command

If you'd like to pass arbitrary arguments to the underlying task command, in addition to the already defined args, you can pass them after --. These arguments are appended as-is.

$ moon run app:typecheck -- --force

The -- delimiter and any arguments must be defined last on the command line.

Next steps