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

Caching System

Commit message caching functionality that enables retry operations and recovery from failed commits by storing commit templates and configuration data.

Capabilities

Cache Value Management

Store and retrieve commit data keyed by repository path for retry functionality.

/**
 * Stores commit data in cache for later retrieval
 * @param cachePath - Path to cache file
 * @param key - Cache key (typically repository path)
 * @param value - Data to store (commit template and options)
 * @returns Updated cache object
 */
function setCacheValueSync(cachePath: string, key: string, value: CacheValue): object;

/**
 * Retrieves cached commit data for a specific repository
 * @param cachePath - Path to cache file
 * @param repoPath - Repository path used as cache key
 * @returns Cached commit data or undefined if not found
 */
function getCacheValueSync(cachePath: string, repoPath: string): CacheValue | undefined;

interface CacheValue {
  template: string;           // Generated commit message template
  options: CommitOptions;     // Original commit options
  overrideOptions: object;    // Override options from adapter
}

Usage Examples:

const path = require('path');
const cacheDir = require('cachedir');
const { cache } = require('commitizen');

// Set up cache paths
const cacheDirectory = cacheDir('commitizen');
const cachePath = path.join(cacheDirectory, 'commitizen.json');
const repoPath = process.cwd();

// Store commit data for retry
const commitData = {
  template: 'feat: add new feature\n\nImplements xyz functionality',
  options: { args: ['--signoff'], quiet: false },
  overrideOptions: { scope: 'api' }
};

cache.setCacheValueSync(cachePath, repoPath, commitData);

// Retrieve cached data for retry
const cachedData = cache.getCacheValueSync(cachePath, repoPath);
if (cachedData) {
  console.log('Found cached commit:', cachedData.template);
  console.log('Original options:', cachedData.options);
  console.log('Override options:', cachedData.overrideOptions);
}

Full Cache Operations

Read and manipulate the entire cache file for advanced operations.

/**
 * Reads the entire cache file
 * @param cachePath - Path to cache file
 * @returns Complete cache object with all stored data
 * @throws Error if cache file cannot be read or parsed
 */
function readCacheSync(cachePath: string): object;

Usage Examples:

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

try {
  // Read entire cache
  const fullCache = cache.readCacheSync(cachePath);
  console.log('All cached repositories:', Object.keys(fullCache));
  
  // Iterate through cached commits
  Object.entries(fullCache).forEach(([repoPath, data]) => {
    console.log(`Repository: ${repoPath}`);
    console.log(`Last commit: ${data.template.split('\n')[0]}`);
  });
  
} catch (error) {
  console.log('No cache file exists yet or cache is corrupted');
}

Cache File Structure

The cache file is stored as JSON with repository paths as keys:

{
  "/path/to/repo1": {
    "template": "feat: add authentication\n\nImplements OAuth2 login flow\n\nCloses #123",
    "options": {
      "args": ["--signoff"],
      "quiet": false,
      "retryLastCommit": false
    },
    "overrideOptions": {
      "scope": "auth"
    }
  },
  "/path/to/repo2": {
    "template": "fix: resolve memory leak\n\nFixes issue with unbounded array growth",
    "options": {
      "args": [],
      "quiet": false
    },
    "overrideOptions": {}
  }
}

Cache Directory Management

Commitizen uses the cachedir package to determine platform-appropriate cache locations:

Linux/macOS: ~/.cache/commitizen/commitizen.json
Windows: %LOCALAPPDATA%/commitizen/commitizen.json

const cacheDir = require('cachedir');
const path = require('path');

// Get platform-specific cache directory
const cacheDirectory = cacheDir('commitizen');
const cachePath = path.join(cacheDirectory, 'commitizen.json');

Integration with Commit Flow

The caching system integrates seamlessly with the commit execution flow:

Normal Commit Flow (with Caching)

User initiates commit with cz
Adapter prompts user for commit information
Template is generated from user responses
Cache stores template and options before git execution
Git commit is executed
On success, cache remains for potential future retry

Retry Commit Flow

User initiates retry with cz --retry
Cache retrieves stored template and options
Git commit is executed directly (no prompting)
On success, cache is updated with successful attempt

// Example of retry integration
const { commit, cache } = require('commitizen');

function retryLastCommit(repoPath, cachePath) {
  const cachedData = cache.getCacheValueSync(cachePath, repoPath);
  
  if (cachedData) {
    // Use cached data for retry
    dispatchGitCommit(
      repoPath,
      cachedData.template,
      cachedData.options,
      cachedData.overrideOptions,
      callback
    );
  } else {
    console.error('No cached commit found for retry');
  }
}

Error Handling and Recovery

The caching system handles various error conditions:

Cache File Issues

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

// Graceful handling of missing cache
try {
  const cachedData = cache.getCacheValueSync(cachePath, repoPath);
} catch (error) {
  console.log('Cache file not found, proceeding with normal commit');
  // Continues with normal commit flow
}

// Graceful handling of corrupted cache
try {
  const fullCache = cache.readCacheSync(cachePath);
} catch (error) {
  console.log('Cache file corrupted, starting fresh');
  // Creates new cache file on next write
}

Automatic Cache Recovery

When cache operations fail, the system continues without caching:

Missing cache directory: Automatically created on first write
Corrupted cache file: Overwritten with new valid cache
Permission issues: Logged but doesn't prevent commit execution
Disk space issues: Handled gracefully with appropriate error messages

Cache Cleanup and Maintenance

While commitizen doesn't provide automatic cache cleanup, the cache can be managed manually:

const fs = require('fs');
const path = require('path');
const cacheDir = require('cachedir');

// Clear all cached commits
function clearCache() {
  const cacheDirectory = cacheDir('commitizen');
  const cachePath = path.join(cacheDirectory, 'commitizen.json');
  
  try {
    fs.unlinkSync(cachePath);
    console.log('Cache cleared successfully');
  } catch (error) {
    console.log('No cache to clear or permission denied');
  }
}

// Remove specific repository from cache
function clearRepoCache(repoPath) {
  const { cache } = require('commitizen');
  const cachePath = path.join(cacheDir('commitizen'), 'commitizen.json');
  
  try {
    const fullCache = cache.readCacheSync(cachePath);
    delete fullCache[repoPath];
    
    fs.writeFileSync(cachePath, JSON.stringify(fullCache, null, '  '));
    console.log(`Cleared cache for ${repoPath}`);
  } catch (error) {
    console.log('Could not update cache');
  }
}

Security Considerations

The cache system stores commit messages in plain text:

Sensitive Information: Avoid including secrets or sensitive data in commit messages
File Permissions: Cache files inherit standard user file permissions
Multi-user Systems: Each user maintains separate cache data
Cleanup: Consider periodic cache cleanup for security-sensitive environments