🌲 ecolog.nvim

<div align="center">

Ecolog (эколог) - your environment guardian in Neovim. Named after the Russian word for "environmentalist", this plugin protects and manages your environment variables with the same care an ecologist shows for nature.

A Neovim plugin for seamless environment variable integration and management. Provides intelligent autocompletion, type checking, and value peeking for environment variables in your projects. All in one place.

💡 LATEST INFO: Please set branch to v1 or consider ecolog2.nvim if possible, ecolog2.nvim is a complete rewrite of ecolog.nvim from the ground up.

</div>

Table of Contents

• Installation
  • Plugin Setup
• Features
• Usage
  • Available Commands
• Environment File Priority
• Shell Variables Integration
  • Basic Usage
  • Advanced Configuration
  • Configuration Options
  • Features
  • Best Practices
• Monorepo Support
  • Configuration
  • Workspace Detection
  • Environment File Resolution
  • Workspace Switching
  • Advanced Configuration
• Variable Interpolation
  • Supported Syntax
  • Examples
  • Configuration Options
  • Features
  • Best Practices
• Supported Languages
  • Currently Supported
  • Adding new languages and custom providers
• Custom Environment File Patterns
  • Basic Usage
  • Pattern Format
  • Examples
  • Features
• Custom Sort Functions
  • File Sorting
  • Variable Sorting
• Integrations
  • Nvim-cmp Integration
  • Blink-cmp Integration
  • Omnifunc Integration
    • Setup
    • Usage
    • Shelter Mode Integration
    • Manual Setup
  • LSP Integration
  • LSP Saga Integration
  • Telescope Integration
  • FZF Integration
  • Snacks Integration
  • Custom Actions for Pickers
  • Statusline Integration
  • AWS Secrets Manager
  • HashiCorp Vault Secrets
• Shelter Previewers
  • Telescope Previewer
  • FZF Previewer
  • Snacks Previewer
• Shelter Mode
  • Configuration
  • Features
    • Module-specific Masking
    • Partial Masking
  • Commands
  • Example
  • Pattern-based Protection
  • Customization
  • Best Practices
• Ecolog Types
  • Type Configuration
  • Custom Type Definition
• Tips
• Theme Integration
• Author Setup
• Comparisons
  • Environment Variable Completion
  • Security Features
  • Environment Management
  • File Management
  • Key Benefits of ecolog.nvim
• Contributing
• License

📦 Installation

Using lazy.nvim:

Plugin Setup

💡 Quick Start: If you want to quickly start with ecolog.nvim, check out the author's personal setup section.

{
  'ph1losof/ecolog.nvim',
  branch = "v1",
  -- Optional: you can add some keybindings
  -- (I personally use lspsaga so check out lspsaga integration or lsp integration for a smoother experience without separate keybindings)
  keys = {
    { '<leader>ge', '<cmd>EcologGoto<cr>', desc = 'Go to env file' },
    { '<leader>ep', '<cmd>EcologPeek<cr>', desc = 'Ecolog peek variable' },
    { '<leader>es', '<cmd>EcologSelect<cr>', desc = 'Switch env file' },
  },
  -- Lazy loading is done internally
  lazy = false,
  opts = {
    integrations = {
        -- WARNING: for both cmp integrations see readme section below
        nvim_cmp = true, -- If you dont plan to use nvim_cmp set to false, enabled by default
        -- If you are planning to use blink cmp uncomment this line
        -- blink_cmp = true,
    },
    -- Enables shelter mode for sensitive values
    shelter = {
        configuration = {
            -- Partial mode configuration:
            -- false: completely mask values (default)
            -- true: use default partial masking settings
            -- table: customize partial masking
            -- partial_mode = false,
            -- or with custom settings:
            partial_mode = {
                show_start = 3,    -- Show first 3 characters
                show_end = 3,      -- Show last 3 characters
                min_mask = 3,      -- Minimum masked characters
            },
            mask_char = "*",   -- Character used for masking
            mask_length = nil, -- Optional: fixed length for masked portion (defaults to value length)
            skip_comments = false, -- Skip masking comment lines in environment files (default: false)
        },
        modules = {
            cmp = true,       -- Enabled to mask values in completion
            peek = false,      -- Enable to mask values in peek view
            files = true, -- Enabled to mask values in file buffers
            telescope = false, -- Enable to mask values in telescope integration
            telescope_previewer = false, -- Enable to mask values in telescope preview buffers
            fzf = false,       -- Enable to mask values in fzf picker
            fzf_previewer = false, -- Enable to mask values in fzf preview buffers
            snacks_previewer = false,    -- Enable to mask values in snacks previewer
            snacks = false,    -- Enable to mask values in snacks picker
        }
    },
    -- true by default, enables built-in types (database_url, url, etc.)
    types = true,
    path = vim.fn.getcwd(), -- Path to search for .env files
    preferred_environment = "development", -- Optional: prioritize specific env files
    -- Controls how environment variables are extracted from code and how cmp works
    provider_patterns = true, -- true by default, when false will not check provider patterns
  },
}

To use the latest features and improvements, you can use the beta branch:

{
  'ph1losof/ecolog.nvim',
  branch = 'beta',
  -- ... rest of your configuration
}

Even though beta branch may contain more experimental changes, new and shiny features will appear faster here. Consider using it as a contribution to the development of the main branch. Since you can share your feedback.

Setup auto-completion with nvim-cmp:

require('cmp').setup({
  sources = {
    { name = 'ecolog' },
    -- your other sources...
  },
})

If you use blink.cmp see Blink-cmp Integration guide

✨ Features

🔍 Advanced Environment Variable Management

• Intelligent variable detection across multiple languages
• Real-time file monitoring and cache updates
• Support for custom environment file patterns
• Priority-based environment file loading
• Shell variables integration
• vim.env synchronization
• Advanced variable interpolation with shell-like syntax

🤖 Smart Autocompletion

• Context-aware suggestions with nvim-cmp and blink-cmp
• Type-safe completions with validation
• Intelligent provider detection
• Language-specific completion triggers
• Comment and metadata support in completions

🛡️ Enhanced Security Features

• Configurable shelter mode for sensitive data
• Partial masking with customizable patterns
• Per-feature security controls
• Real-time visual masking
• Temporary value reveal functionality
• Screen sharing protection

🔄 Integrations

• LSP integration for hover and definition
• Telescope integration with fuzzy finding
• FZF integration with preview support
• LSP Saga integration
• Custom provider API for language support

📁 Multi-Environment Support

• Multiple .env file handling
• Custom file pattern matching
• Priority-based loading system
• Environment-specific configurations
• Custom sort functions for file priority

🏢 Monorepo Support

• Automatic workspace detection (Turborepo, Nx, Lerna, Rush, etc.)
• Intelligent environment file resolution strategies
• Workspace-aware variable completion and display
• Automatic and manual workspace switching
• Cross-workspace environment file management

💡 Type System

• Built-in type validation
• Custom type definitions
• Pattern-based type detection
• Value transformation support
• Type-aware completion and validation

🎨 UI/UX Features

• T