Configuration Reference#

Complete reference for Dirvana configuration files.

Configuration Files#

Dirvana supports two types of configuration files:

Global config: ~/.config/dirvana/global.yml - Applied to all projects
Local configs: .dirvana.yml in project directories - Project-specific settings

Configuration files are merged in this order: global → root → parent → current directory (child configs override parent values).

Basic Structure#

# yaml-language-server: $schema=https://raw.githubusercontent.com/NikitaCOEUR/dirvana/main/schema/dirvana.schema.json

# Aliases
aliases:
  ll: ls -lah
  k:
    command: kubectl
    completion: kubectl

# Functions
functions:
  mkcd: |
    mkdir -p "$1" && cd "$1"

# Environment variables
env:
  PROJECT_NAME: myproject
  GIT_BRANCH:
    sh: git rev-parse --abbrev-ref HEAD

# Flags
local_only: false      # Don't merge with parent configs
ignore_global: false   # Don't merge with global config

Aliases#

Simple Aliases#

aliases:
  ll: ls -lah
  gs: git status
  build: go build -o bin/app ./cmd

Aliases with Auto-Completion#

aliases:
  k:
    command: kubectl
    completion: kubectl  # Inherits kubectl completion!

  g:
    command: git
    completion: git

  tf:
    command: terraform
    completion: terraform

Functions#

Define reusable shell functions:

functions:
  # Create directory and cd into it
  mkcd: |
    mkdir -p "$1" && cd "$1"

  # Greeting function
  greet: |
    echo "Hello, $1!"

  # Complex function
  backup: |
    timestamp=$(date +%Y%m%d_%H%M%S)
    tar -czf "backup_${timestamp}.tar.gz" "$1"
    echo "Backup created!"

Environment Variables#

Static Values#

env:
  PROJECT_NAME: myproject
  LOG_LEVEL: debug
  TF_LOG: info

Dynamic Values#

env:
  # Execute shell command
  GIT_BRANCH:
    sh: git rev-parse --abbrev-ref HEAD

  PROJECT_NAME:
    sh: basename $(pwd)

  CURRENT_USER:
    sh: whoami

  GIT_REPOSITORY:
    sh: git remote get-url origin | sed 's/.*github.com:\(.*\)\.git/\1/'

Security Note: Dynamic environment variables require explicit user authorization to prevent execution of untrusted code.

Template Variables#

env:
  # Directory where .dirvana.yml is located
  PROJECT_ROOT: "{{.DIRVANA_DIR}}"

  # Extract directory name
  PROJECT_NAME: "{{.DIRVANA_DIR | base}}"

  # Build paths
  BUILD_DIR: "{{.DIRVANA_DIR}}/build"

  # Generate unique ID
  PROJECT_ID: "{{.DIRVANA_DIR | sha256sum | trunc 8}}"

See Template Variables for more details.

Configuration Flags#

`local_only`#

Prevent merging with parent directory configurations:

local_only: true

`ignore_global`#

Ignore global configuration:

ignore_global: true

Commands Reference#

dirvana init#

Create a sample configuration file:

dirvana init

dirvana edit#

Open/create configuration in your editor:

dirvana edit

dirvana validate#

Validate configuration file:

dirvana validate
dirvana validate /path/to/.dirvana.yml

dirvana status#

Show current configuration status:

dirvana status

dirvana allow / revoke#

Manage authorization:

dirvana allow                # Authorize current directory
dirvana revoke               # Revoke authorization
dirvana list                 # List authorized projects

IDE Integration#

Enable auto-completion and validation:

YAML Language Server#

# yaml-language-server: $schema=https://raw.githubusercontent.com/NikitaCOEUR/dirvana/main/schema/dirvana.schema.json

VS Code#

Add to .vscode/settings.json:

{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/NikitaCOEUR/dirvana/main/schema/dirvana.schema.json": [
      ".dirvana.yml"
    ]
  }
}

Generate Schema Locally#

dirvana schema -o .vscode/dirvana.schema.json

Next Steps#

Advanced Features