Commitlint Travis CLI

A zero-configuration commit message linting CLI tool specifically designed for Travis CI environments. It provides intelligent commit range detection and seamless integration with Travis CI build processes, automatically determining which commits to lint based on the build context (pull request vs single commit).

Package Information

• Package Name: @commitlint/travis-cli
• Package Type: npm
• Language: TypeScript
• Node.js Requirements: >=v18
• Installation: npm install --save-dev @commitlint/travis-cli

Core Imports

This package provides a CLI binary rather than programmatic imports:

# Binary command available after installation
commitlint-travis

Basic Usage

Add to your Travis CI configuration:

# .travis.yml
script:
  - commitlint-travis

The tool automatically detects the appropriate commit range based on Travis CI environment variables and passes any additional arguments to the underlying commitlint command:

# With additional commitlint options
commitlint-travis --config ./config/commitlint.config.js --verbose

Architecture

The tool operates as a wrapper around @commitlint/cli with the following key components:

• Environment Validation: Ensures proper Travis CI context and required environment variables
• Git Repository Management: Handles remote setup, stashing, and restoration for clean PR validation
• Intelligent Range Detection: Automatically determines commit scope based on build type
• Commitlint Integration: Passes through all arguments to the underlying commitlint tool

Capabilities

CLI Command

The primary interface is the commitlint-travis binary command that automatically handles commit message linting in Travis CI environments.

commitlint-travis [commitlint-options...]

Parameters:

• commitlint-options: Any valid commitlint CLI options (passed through unchanged to underlying @commitlint/cli command)

Dependencies:

• @commitlint/cli: The underlying commitlint command-line interface
• tinyexec: Used for spawning child processes
• Built-in Node.js modules: node:child_process, node:module

Environment Requirements:

• CI="true" - Must be running in CI environment
• TRAVIS="true" - Must be running on Travis CI
• TRAVIS_COMMIT - Current commit hash being built
• TRAVIS_COMMIT_RANGE - Range of commits for pull requests
• TRAVIS_EVENT_TYPE - Build event type (e.g., "pull_request")
• TRAVIS_REPO_SLUG - Repository slug (owner/repo)
• TRAVIS_PULL_REQUEST_SLUG - Pull request source repository slug

Execution Sequence:

1. Environment Validation: Verifies Travis CI environment variables are present
2. Working Directory Stashing: Stashes any uncommitted changes using git stash -k -u --quiet (only if working directory is not clean)
3. Remote Setup: Adds git remotes for the base repository and source repository (for PRs)
   • Base remote: git remote add base https://github.com/${TRAVIS_REPO_SLUG}.git
   • Source remote (PR only): git remote add source https://github.com/${TRAVIS_PULL_REQUEST_SLUG}.git
4. Repository Fetching: Fetches latest commits from remotes using git fetch --quiet
5. Working Directory Restoration: Pops stashed changes using git stash pop --quiet
6. Commit Linting: Executes appropriate commitlint command based on build type

Behavior Modes:

• Pull Request Mode: When TRAVIS_EVENT_TYPE === "pull_request" and TRAVIS_COMMIT_RANGE is available, parses the range (format: "commit1.commit2") and lints all commits using commitlint --from <start> --to <end>
• Single Commit Mode: For regular commits, retrieves the commit message using git log -n 1 --pretty=format:%B <commit> and pipes it to commitlint for validation

Usage Example:

# Basic usage (in .travis.yml)
script:
  - commitlint-travis

# With custom configuration
script:
  - commitlint-travis --config ./custom-commitlint.config.js

# With verbose output
script:
  - commitlint-travis --verbose --help-url https://company.com/commit-guidelines

Environment Variable Overrides

For testing and customization purposes, the tool supports environment variable overrides:

# Override git binary path (primarily for testing)
TRAVIS_COMMITLINT_GIT_BIN=/path/to/git

# Override commitlint binary path (primarily for testing)  
TRAVIS_COMMITLINT_BIN=/path/to/commitlint

Error Handling

The tool performs comprehensive validation and provides clear error messages:

Environment Validation Errors:

• Throws error if not running on Travis CI (CI !== "true" or TRAVIS !== "true")
  • Error message: "@commitlint/travis-cli is intended to be used on Travis CI"
• Throws error if required environment variables are missing, with specific details:
  • Single missing variable: "Expected <VAR_NAME> to be defined globally, it was not."
  • Multiple missing variables: "Expected <VAR1>, <VAR2>, ... to be defined globally, they were not."

Git Operation Errors:

• Propagates git command failures with full error details
• Git operations that may fail: git stash, git remote add, git fetch, git stash pop
• Working directory restoration is attempted even if other operations fail
• All git commands inherit stdio from parent process for error visibility

Commitlint Execution Errors:

• Forwards commitlint exit codes and error output unchanged
• Preserves all commitlint error formatting and reporting
• Commitlint receives piped input (commit message) for single commit mode
• Command-line arguments are passed through unchanged to commitlint

Integration Patterns

Travis CI Configuration

# .travis.yml - Basic setup
language: node_js
node_js:
  - "18"

install:
  - npm ci

script:
  - npm test
  - commitlint-travis

# For monorepos or complex configurations
script:
  - commitlint-travis --config ./packages/lint-config/commitlint.config.js

Package.json Integration

{
  "devDependencies": {
    "@commitlint/travis-cli": "^19.8.1",
    "@commitlint/config-conventional": "^19.8.1"
  },
  "scripts": {
    "lint:commits": "commitlint-travis"
  }
}

Custom Commitlint Configuration

The tool works with any commitlint configuration:

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore']],
    'subject-max-length': [2, 'always', 72]
  }
};