or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

adapter.md cache.md cli.md commit.md config.md git.md index.md init.md staging.md

tile.json

Commit Execution

Core commit functionality that handles interactive prompting, message generation, caching, and git command execution with support for retry operations and git hooks.

Capabilities

Main Commit Function

Executes the complete commit workflow including prompting, caching, and git integration.

/**
 * Asynchronously commits files using commitizen with interactive prompting
 * @param inquirer - Inquirer.js instance for user prompts
 * @param repoPath - Path to git repository
 * @param prompter - Adapter prompter function
 * @param options - Commit execution options
 * @param done - Callback function called on completion
 */
function commit(
  inquirer: object,
  repoPath: string,
  prompter: PrompterFunction,
  options: CommitOptions,
  done: ErrorCallback
): void;

interface CommitOptions {
  args?: string[];              // Additional git commit arguments
  disableAppendPaths?: boolean; // Disable appending file paths to commit
  emitData?: boolean;           // Emit commit data events
  quiet?: boolean;              // Suppress git command output
  retryLastCommit?: boolean;    // Retry last cached commit attempt
  hookMode?: boolean;           // Use git hook mode (write to COMMIT_EDITMSG)
}

type ErrorCallback = (error: Error | null, template?: string) => void;
type PrompterFunction = (
  inquirer: object,
  callback: (error: Error | null, template: string, overrideOptions?: object) => void
) => void;

Usage Examples:

const inquirer = require('inquirer');
const { commit, adapter } = require('commitizen');

// Basic commit usage
const prompter = adapter.getPrompter('cz-conventional-changelog');

commit(inquirer, process.cwd(), prompter, {
  args: ['--signoff'],
  quiet: false
}, (error, template) => {
  if (error) {
    console.error('Commit failed:', error.message);
    process.exit(1);
  }
  console.log('Commit successful!');
  console.log('Used template:', template);
});

// Retry last commit
commit(inquirer, process.cwd(), prompter, {
  retryLastCommit: true
}, (error) => {
  if (error) {
    console.error('Retry failed:', error.message);
  } else {
    console.log('Retry successful!');
  }
});

// Hook mode for git prepare-commit-msg
commit(inquirer, process.cwd(), prompter, {
  hookMode: true,
  quiet: true
}, (error) => {
  // Writes commit message to .git/COMMIT_EDITMSG instead of executing git commit
});

Git Commit Dispatch

Lower-level function that executes the actual git commit command.

/**
 * Dispatches git commit with the generated message template
 * @param repoPath - Path to git repository  
 * @param template - Formatted commit message template
 * @param options - Base commit options
 * @param overrideOptions - Additional options from adapter
 * @param done - Callback function
 */
function dispatchGitCommit(
  repoPath: string,
  template: string,
  options: CommitOptions,
  overrideOptions: object,
  done: ErrorCallback
): void;

Commit Flow

The commit process follows these steps:

Cache Directory Setup: Creates commitizen cache directory for storing commit templates
Retry Check: If retryLastCommit is true, loads cached commit data and skips prompting
Interactive Prompting: Uses adapter prompter to gather commit information from user
Template Generation: Adapter generates commit message template from user input
Caching: Stores commit template and options for potential retry
Git Execution: Executes git commit with generated message or writes to COMMIT_EDITMSG

Caching Integration

Commit execution integrates with the caching system for retry functionality:

// Cache structure for retry operations
const cacheData = {
  template: "feat: add new feature\n\nImplements XYZ functionality",
  options: { args: ['--signoff'], quiet: false },
  overrideOptions: { scope: 'api' }
};

Hook Mode Support

Hook mode allows integration with git hooks like prepare-commit-msg:

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

// In prepare-commit-msg hook
commit(inquirer, process.cwd(), prompter, {
  hookMode: true,    // Writes to .git/COMMIT_EDITMSG
  quiet: true        // Suppress output in hook context
}, (error) => {
  if (error) process.exit(1);
  process.exit(0);
});

Error Handling

Commit execution handles various error scenarios:

Adapter Errors: Prompter function failures are passed through to callback
Cache Directory Issues: Warns about cache creation failures but continues execution
Git Command Failures: Provides specific error codes and helpful messages
Empty Commits: Integration with staging validation to prevent accidental empty commits
Interrupted Prompts: Graceful handling of user cancellation (Ctrl+C)

Template Processing

Commit templates support various formats and processing:

Multi-line Messages: Full support for conventional commit formats with body and footer
Dedent Processing: Automatic indentation normalization using dedent library
Variable Substitution: Templates can include dynamic content from prompter responses
Override Options: Adapters can provide additional git command options

Template Example:

// Generated by adapter
const template = `feat(auth): add OAuth2 integration

Implements OAuth2 authentication flow with support for:
- Authorization code flow
- Token refresh
- Scope validation

Closes #123
Breaking-change: Updates authentication API`;

// Override options from adapter
const overrideOptions = {
  args: ['--author="Automated System <auto@example.com>"']
};