Configuration

While task-graph works well out of the box, a configuration file gives you full control over the appearance of the generated graph. Configuration files can be written in YAML or JSON and are passed via the --config flag:

task-graph Taskfile.yml --output taskfile.dot --config config.yaml

Settings specified on the command line take precedence over values in the configuration file, so you can use a config file for your baseline and override individual settings per invocation.

A minimal example

The simplest useful configuration defines a few style rules to colour tasks by category:

nodeStyleRules:
  - match: "build*"
    fillColor: lightyellow
  - match: "tidy*"
    fillColor: lightgreen
  - match: "*test*"
    fillColor: lightblue
  - match: "lint"
    fillColor: magenta

Full configuration reference

Here is a complete example showing every available setting with its default value:

# Group tasks by namespace in the output
groupByNamespace: false

# Type of graph to generate: "dot" or "mermaid"
graphType: dot

# Fill colour used for highlighted tasks (see --highlight)
highlightColor: yellow

# Automatically colour nodes by namespace
autoColor: false

# Path to the dot executable (or a directory containing it).
# Leave empty to search the system PATH.
dotPath: ""

# Pattern-based style rules applied to task nodes
nodeStyleRules:
  - match: "build*"
    color: black
    fillColor: powderblue
    style: filled
    fontColor: black

# Graphviz-specific settings (ignored for Mermaid output)
graphviz:
  font: Verdana
  fontSize: 16
  taskNodes:
    color: black
    fillColor: ""
    style: ""
    fontColor: ""
  dependencyEdges:
    color: black
    width: 1
    style: solid
  callEdges:
    color: blue
    width: 1
    style: dashed

# Mermaid-specific settings (ignored for Graphviz output)
mermaid:
  direction: TD

Node style rules

Style rules are the primary mechanism for customising the appearance of individual tasks. Each rule has a match pattern and one or more visual properties.

Pattern matching

The match field accepts glob-style patterns:

• * matches any sequence of characters
• ? matches a single character
• [abc] matches any one of the characters listed

A few examples:

Rules are applied in order, and where a task matches multiple rules, the last matching rule wins for any conflicting property. This means you can define broad rules first and narrow overrides later:

nodeStyleRules:
  - match: "*"
    fillColor: white
  - match: "build*"
    fillColor: powderblue
  - match: "build:release"
    fillColor: gold

Available properties

Each rule can set any combination of the following:

Colours can be specified using any Graphviz colour name or a hex value. When you set fillColor, the filled style is applied automatically — you do not need to set style explicitly in that case.

Graphviz settings

The graphviz section controls settings specific to Graphviz .dot output. These settings are ignored when generating Mermaid graphs.

Font

graphviz:
  font: Verdana
  fontSize: 16

The font and fontSize values apply to all labels in the graph — node labels, edge labels, and cluster labels. The default font is Verdana at 16 points, which works well at a range of graph sizes.

Default node appearance

graphviz:
  taskNodes:
    color: black
    fillColor: ""
    style: ""
    fontColor: ""

The taskNodes section defines the default appearance for all task nodes before any style rules are applied. This is useful if you want every node to have a consistent baseline — for example, a light background — without writing a catch-all rule.

Edge appearance

graphviz:
  dependencyEdges:
    color: black
    width: 1
    style: solid
  callEdges:
    color: blue
    width: 1
    style: dashed

Dependency edges (solid lines by default) represent tasks listed under deps: in your Taskfile. Call edges (dashed blue lines by default) represent tasks invoked from cmds: using task: otherTask.

You can adjust the colour, line width, and style for each type independently. Supported styles include solid, dashed, dotted, and bold.

Mermaid settings

The mermaid section controls settings specific to Mermaid output. Currently, the only available setting is the flow direction:

mermaid:
  direction: TD

Bootstrapping a config file

Rather than writing a configuration file from scratch, you can use --export-config to capture the effective configuration — including all defaults and any CLI flags you have specified — and use that as a starting point:

task-graph Taskfile.yml --output taskfile.dot --auto-color --export-config config.yaml

This writes the fully merged configuration to config.yaml. You can then edit the file to taste, remove settings you do not need, and pass it back with --config on subsequent runs.

A real-world example

Here is the configuration used for the Azure Service Operator project, demonstrating how to combine Graphviz styling with node style rules for a large Taskfile:

graphviz:
  font: Verdana
  fontSize: 16
  dependencyEdges:
    color: black
    width: 1
    style: solid
  callEdges:
    color: blue
    width: 1
    style: dashed
  taskNodes:
    color: black
nodeStyleRules:
  - match: "build*"
    fillColor: powderblue
  - match: "*test*"
    fillColor: aquamarine
  - match: "*lint*"
    fillColor: aquamarine
  - match: "*tidy*"
    fillColor: cornsilk
  - match: "*doc*"
    fillColor: plum1

This configuration assigns distinct colours to different categories of work — build tasks in blue, testing and linting in green, tidying in cream, and documentation in purple — making it straightforward to scan a large graph and find the area you care about.

Configuration