Including Other Files and Projects
Local Files
A good organizational tool is to break your project.visivo.yml
into multiple local files based on organizational needs. An example of this would be to put all your models
in one file and reference that file like:
includes:
- path: models.yml
You may wish to organization it along a different axis, for example one file per dashboard like:
includes:
- path: finance_dashboard.yml
- path: operation_dashboard.yml
Use whatever system best matches your use case.
Your includes can include other includes, allowing for nesting. Be wise!
Directory Inclusion
For larger projects with many YAML files, you can include entire directories instead of listing individual files. By default, Visivo will recursively search through all subdirectories and include all .yml
and .yaml
files:
includes:
- path: ./config/
Controlling Directory Depth
You can control how deep Visivo searches within directories using the depth
parameter:
includes:
# Include only files directly in the config directory (no subdirectories)
- path: ./config/
depth: 0
# Include files in config directory and one level of subdirectories
- path: ./models/
depth: 1
# Fully recursive search (default behavior)
- path: ./all-files/
depth: null # or omit depth entirely
depth: 0
- Only files in the specified directory (no subdirectories)depth: 1
- Files in the directory and one level of subdirectoriesdepth: null
or omitted - Fully recursive search through all subdirectories (default)
Excluding Files and Directories
Use the exclusions
parameter to skip specific files or directories. Exclusions support multiple pattern types:
includes:
- path: ./config/
exclusions:
- "*.backup.yml" # Exclude all .backup.yml files
- "temp_config.yml" # Exclude specific file by name
- "*/temp/*" # Exclude anything in temp directories
- "*/archive/*" # Exclude anything in archive directories
- "*.config.yml" # Exclude configuration template files
Advanced Directory Examples
Combine depth control and exclusions for precise file selection:
includes:
# Include all YAML files recursively, but skip backup and temp files
- path: ./project-configs/
exclusions:
- "*.backup.yml"
- "*.temp.yml"
- "*/backup/*"
- "*/temp/*"
# Include only top-level model files, skip nested configurations
- path: ./models/
depth: 0
exclusions:
- "*.config.yml"
# Include specific dashboard subdirectories but exclude test files
- path: ./dashboards/
depth: 2
exclusions:
- "*test*"
- "*/drafts/*"
Pattern Matching for Exclusions
Exclusions support several pattern matching approaches:
- Filename patterns:
*.backup.yml
,temp_*
- Path patterns:
*/temp/*
,config/*/old/*
- Exact names:
old_config.yml
,deprecated.yml
- Regex patterns: Advanced users can use regex for complex matching
The exclusion patterns are matched against both the filename and the relative path from the include directory.
External Projects
One of the most powerful aspects of Visivo is the ability to include public GitHub repos that contain Visivo dashboards in your project. This gives everyone to share a useful dashboard that they may have.
We have published a series of projects that allow you to quickly build dashboards based on some popular tools.
Those are tagged in GitHub here.
You can also build and share your own under the same visivo-dashboard
topic in GitHub.
Here is an example on how to include our dashboard that provides insights into your repositories' pull requests:
includes:
- path: visivo-io/github-dashboard.git@main
Once it is included then you can reference the traces
and charts
like you would if they were in your project like:
dashboards:
- name: Github Metrics
rows:
- height: medium
items:
- width: 1
chart:
name: Pull Requests by Repository
traces:
- ${ref(Pull Request by Repository)}
layout:
title: "Pull Request by Repository"