tessl/npm-commitizen
Command-line utility for creating standardized Git commit messages through interactive prompts and adapter system.
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Securityby
Pending
The risk profile of this skill
init.mddocs/
Project Initialization
Adapter installation and project configuration functionality for setting up commitizen in new and existing projects.
Capabilities
Initialize Adapter
Main initialization function that installs adapters and configures projects for commitizen usage.
/**
* Installs commitizen adapter and configures project
* @param repoPath - Path to repository root
* @param adapterNpmName - NPM package name of adapter to install
* @param options - Installation and configuration options
* @throws Error if required arguments are missing or installation fails
*/
function init(
repoPath: string,
adapterNpmName: string,
options?: InitOptions
): void;
interface InitOptions {
save?: boolean; // Add to dependencies (npm)
saveDev?: boolean; // Add to devDependencies (npm/pnpm)
saveExact?: boolean; // Install exact version (npm/pnpm)
force?: boolean; // Force install over existing adapter
yarn?: boolean; // Use yarn package manager
dev?: boolean; // Add to devDependencies (yarn)
exact?: boolean; // Install exact version (yarn)
pnpm?: boolean; // Use pnpm package manager
includeCommitizen?: boolean; // Also install commitizen package
}Usage Examples:
const { init } = require('commitizen');
// Basic initialization with npm
init(process.cwd(), 'cz-conventional-changelog', {
saveDev: true,
saveExact: true
});
// Force installation over existing adapter
init(process.cwd(), 'cz-conventional-changelog', {
saveDev: true,
force: true
});
// Yarn installation
init(process.cwd(), 'cz-conventional-changelog', {
yarn: true,
dev: true,
exact: true
});
// pnpm installation with commitizen included
init(process.cwd(), 'cz-conventional-changelog', {
pnpm: true,
saveDev: true,
saveExact: true,
includeCommitizen: true
});Default Options
The initialization function uses sensible defaults for most scenarios:
const defaultInitOptions: InitOptions = {
save: false, // Don't add to dependencies by default
saveDev: true, // Add to devDependencies by default
saveExact: false, // Allow version ranges by default
force: false, // Don't force install by default
yarn: false, // Use npm by default
dev: true, // Add to devDependencies (yarn equivalent)
exact: false, // Allow version ranges (yarn equivalent)
pnpm: false, // Use npm by default
};Argument Validation
Built-in validation ensures required parameters are provided:
/**
* Validates required arguments for initialization
* @param path - Repository path (must be provided)
* @param adapterNpmName - Adapter package name (must be provided)
* @throws Error if required arguments are missing
*/
function checkRequiredArguments(path: string, adapterNpmName: string): void;Configuration Loading
Loads existing adapter configuration to prevent conflicts:
/**
* Loads existing adapter configuration from project
* @param cwd - Working directory to search for config
* @returns Existing commitizen configuration or undefined
*/
function loadAdapterConfig(cwd: string): CommitizenConfig | undefined;
interface CommitizenConfig {
path: string; // Path to adapter module
}Installation Process
The initialization process follows these steps:
- Argument Validation: Ensures required parameters are provided
- Configuration Check: Loads existing adapter configuration
- Conflict Resolution: Checks for existing adapters (fails unless
force: true) - Package Manager Selection: Chooses npm, yarn, or pnpm based on options
- Flag Mapping: Maps generic options to package manager-specific flags
- Command Generation: Creates appropriate install command string
- Adapter Installation: Executes package manager install command
- Commitizen Installation: Optionally installs commitizen if
includeCommitizen: true - Configuration Update: Updates package.json with adapter path configuration
Package Manager Support
NPM Installation
# Generated command example
npm install cz-conventional-changelog --save-dev --save-exact// Usage
init(process.cwd(), 'cz-conventional-changelog', {
saveDev: true,
saveExact: true
});Yarn Installation
# Generated command example
yarn add cz-conventional-changelog --dev --exact// Usage
init(process.cwd(), 'cz-conventional-changelog', {
yarn: true,
dev: true,
exact: true
});PNPM Installation
# Generated command example
pnpm add cz-conventional-changelog --save-dev --save-exact// Usage
init(process.cwd(), 'cz-conventional-changelog', {
pnpm: true,
saveDev: true,
saveExact: true
});Configuration Output
After successful initialization, the following configuration is added to package.json:
{
"config": {
"commitizen": {
"path": "./node_modules/cz-conventional-changelog"
}
}
}Error Handling
Initialization handles various error conditions:
- Missing Arguments: Clear error messages for required parameters
- Existing Configuration: Prevents accidental overwrite unless
force: true - Installation Failures: Reports package manager errors with context
- File System Errors: Handles permission issues and missing directories
- Invalid Adapters: Validates adapter package names and availability
Error Examples:
// Missing required arguments
try {
init(); // Missing both arguments
} catch (error) {
console.error(error.message); // "Path is required when running init."
}
// Existing adapter without force flag
try {
init(process.cwd(), 'new-adapter'); // Existing adapter configured
} catch (error) {
console.error(error.message);
// "A previous adapter is already configured. Use --force to override"
}
// Installation failure
try {
init(process.cwd(), 'nonexistent-adapter');
} catch (error) {
console.error('Installation failed:', error.message);
}Advanced Usage
Custom Adapter Paths
Initialize with local or custom adapter paths:
// Local adapter
init(process.cwd(), './custom-adapters/my-adapter', {
saveDev: true
});
// Scoped package
init(process.cwd(), '@company/cz-adapter', {
saveDev: true,
saveExact: true
});Multi-Package Installation
Install commitizen along with the adapter:
init(process.cwd(), 'cz-conventional-changelog', {
saveDev: true,
includeCommitizen: true // Also installs commitizen package
});