or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

adapter.mdcache.mdcli.mdcommit.mdconfig.mdgit.mdindex.mdinit.mdstaging.md
tile.json

config.mddocs/

Configuration Loading

Multi-source configuration resolution system that loads commitizen settings from various file formats and locations with intelligent priority ordering.

Capabilities

Main Configuration Loader

Loads commitizen configuration from multiple sources with automatic format detection.

/**
 * Loads commitizen configuration from standard locations
 * @param config - Optional configuration override
 * @param cwd - Working directory to search (defaults to process.cwd())
 * @returns Loaded configuration object or undefined if not found
 */
function load(config?: object, cwd?: string): CommitizenConfig | undefined;

interface CommitizenConfig {
  path: string;          // Path to adapter module
  [key: string]: any;    // Additional adapter-specific configuration
}

Usage Examples:

const { configLoader } = require('commitizen');

// Load config from current directory
const config = configLoader.load();
if (config) {
  console.log('Adapter path:', config.path);
} else {
  console.log('No commitizen configuration found');
}

// Load config from specific directory
const projectConfig = configLoader.load(null, '/path/to/project');

// Override with custom config
const customConfig = configLoader.load({
  path: 'cz-custom-adapter'
}, process.cwd());

Generic Configuration Loader

Lower-level loader that can be configured for different file sources and formats.

/**
 * Generic configuration loader with customizable file sources
 * @param configs - Array of configuration file names to search
 * @param config - Optional configuration override
 * @param cwd - Working directory to search
 * @returns Loaded and normalized configuration object
 */
function loader(
  configs: string[],
  config?: object,
  cwd?: string
): object | undefined;

File Discovery

Find configuration files up the directory tree with pattern matching.

/**
 * Find files matching patterns up the directory tree
 * @param patterns - Array of glob patterns to match
 * @param options - Search options with cwd and other glob options
 * @param fn - Filter function to validate found files
 * @returns Full path to first matching file or undefined
 */
function findup(
  patterns: string[],
  options: { cwd: string; nocase?: boolean },
  fn: (configPath: string) => boolean
): string | undefined;

Content Loading

Load and parse configuration file content with format detection.

/**
 * Get content of a configuration file with automatic parsing
 * @param configPath - Path to configuration file (relative or absolute)
 * @param baseDirectory - Base directory to resolve relative paths
 * @returns Parsed configuration object or undefined
 */
function getContent(configPath: string, baseDirectory: string): object | undefined;

/**
 * Normalize configuration content based on file type and structure
 * @param config - Configuration file name or path
 * @param content - Raw configuration content
 * @returns Normalized commitizen configuration
 */
function getNormalizedConfig(config: string, content?: object): object | undefined;

Usage Examples:

const { configLoader } = require('commitizen');

// Custom configuration sources
const customConfig = configLoader.loader(
  ['.myrc', '.my.json', 'package.json'],
  null,
  process.cwd()
);

// Standard commitizen sources
const standardConfig = configLoader.loader(
  ['.czrc', '.cz.json', 'package.json'],
  null,
  process.cwd()
);

// Find configuration files manually
const configPath = configLoader.findup(
  ['.czrc', '.cz.json'],
  { cwd: process.cwd(), nocase: true },
  (path) => {
    // Validate config file
    console.log('Found config at:', path);
    return true;
  }
);

// Load specific configuration file
if (configPath) {
  const content = configLoader.getContent(configPath, process.cwd());
  const normalized = configLoader.getNormalizedConfig('package.json', content);
}

// Direct content loading
const packageConfig = configLoader.getContent('package.json', './my-project');
const czrcConfig = configLoader.getContent('.czrc', process.cwd());

Configuration Sources

Commitizen searches for configuration in the following files, in priority order:

1. .czrc File

JSON format configuration file with direct commitizen settings:

{
  "path": "cz-conventional-changelog",
  "maxHeaderWidth": 100,
  "maxLineWidth": 100
}

2. .cz.json File

Alternative JSON format for commitizen configuration:

{
  "path": "cz-conventional-changelog",
  "scopes": ["api", "ui", "docs"],
  "allowCustomScopes": true
}

3. package.json Configuration

Configuration embedded in package.json under the config.commitizen key:

{
  "name": "my-project",
  "version": "1.0.0",
  "config": {
    "commitizen": {
      "path": "cz-conventional-changelog",
      "maxHeaderWidth": 72
    }
  }
}

Configuration File Utilities

File Discovery

Searches up the directory tree for configuration files:

/**
 * Finds configuration files by searching up directory tree
 * @param configs - Array of file names to search for
 * @param cwd - Starting directory for search
 * @returns Object mapping found files to their paths
 */
function findup(configs: string[], cwd?: string): { [filename: string]: string };

Usage Examples:

const { configLoader } = require('commitizen');

// Find all config files
const foundFiles = configLoader.findup(['.czrc', '.cz.json', 'package.json']);
console.log('Found configs:', foundFiles);
// Result: { '.czrc': '/path/to/.czrc', 'package.json': '/path/to/package.json' }

Content Loading

Loads and parses configuration file content with format detection:

/**
 * Loads content from configuration file with automatic format detection
 * @param filepath - Path to configuration file
 * @param filename - Name of the file (used for format detection)
 * @returns Parsed configuration object
 */
function getContent(filepath: string, filename: string): object | undefined;

Usage Examples:

const { configLoader } = require('commitizen');

// Load .czrc file
const czrcContent = configLoader.getContent('/path/to/.czrc', '.czrc');

// Load package.json commitizen config
const packageContent = configLoader.getContent('/path/to/package.json', 'package.json');
// Automatically extracts config.commitizen section

Configuration Normalization

Normalizes loaded configuration to standard format:

/**
 * Normalizes configuration object to standard commitizen format
 * @param config - Raw configuration object
 * @param filename - Source filename for context
 * @returns Normalized configuration
 */
function getNormalizedConfig(config: object, filename: string): CommitizenConfig | undefined;

File Format Support

JSON Files (.czrc, .cz.json)

Direct JSON format with commitizen configuration at root level:

{
  "path": "cz-conventional-changelog",
  "maxHeaderWidth": 100,
  "maxLineWidth": 100,
  "scopes": ["feat", "fix", "docs"],
  "allowCustomScopes": true,
  "allowBreakingChanges": ["feat", "fix"]
}

Package.json Integration

Configuration embedded under config.commitizen key:

{
  "name": "my-project",
  "scripts": {
    "commit": "cz"
  },
  "config": {
    "commitizen": {
      "path": "cz-conventional-changelog"
    }
  },
  "devDependencies": {
    "commitizen": "^4.0.0",
    "cz-conventional-changelog": "^3.0.0"
  }
}

JSON with Comments

Support for JSON files with JavaScript-style comments:

{
  // Primary adapter configuration
  "path": "cz-conventional-changelog",
  
  /* Display configuration */
  "maxHeaderWidth": 100,
  "maxLineWidth": 100
}

Configuration Priority

When multiple configuration sources exist, they are processed in this priority order:

  1. Override parameter - Explicitly passed config object
  2. .czrc - Dedicated commitizen configuration file
  3. .cz.json - Alternative JSON configuration file
  4. package.json - Configuration in package.json config.commitizen

Higher priority sources completely override lower priority ones (no merging).

Error Handling

Configuration loading handles various error conditions gracefully:

  • Missing Files: Returns undefined for missing configuration
  • Invalid JSON: Logs parsing errors and continues to next source
  • Malformed Config: Validates required fields and structure
  • File Permission Issues: Handles access errors without crashing
  • Encoding Issues: Supports UTF-8 encoding with BOM handling

Error Examples:

const { configLoader } = require('commitizen');

// Graceful handling of missing config
const config = configLoader.load();
if (!config) {
  console.log('No configuration found, using defaults');
}

// Handle specific directory
try {
  const config = configLoader.load(null, '/nonexistent/path');
  console.log('Config:', config); // Will be undefined
} catch (error) {
  console.error('Configuration loading failed:', error.message);
}

Advanced Configuration

Custom File Sources

Configure loader for custom file patterns:

const { configLoader } = require('commitizen');

// Search custom files
const customSources = ['.commitizenrc', '.commit.json', 'package.json'];
const config = configLoader.loader(customSources, null, process.cwd());

Configuration Validation

Validate loaded configuration:

const config = configLoader.load();
if (config && config.path) {
  console.log('Valid configuration found');
  console.log('Adapter:', config.path);
} else {
  console.error('Invalid or missing configuration');
}