Skip to content

Ignoring Files & Extensions

Jump to bottom
Griffen Fargo edited this page Oct 6, 2025 · 6 revisions

In some scenarios, you may want to exclude certain files or file extensions from being considered by coco when generating commit messages. This can be particularly useful for files that frequently change but don't significantly contribute to the context or content of a commit, such as package lock files, generated files, or build artifacts.

Why Ignore Files?

Ignoring certain files helps coco focus on meaningful changes by excluding:

  • Lock files that change automatically with dependency updates
  • Generated files that are created by build processes
  • Large binary files that don't provide useful context
  • Temporary files that aren't part of the actual codebase
  • Log files and debug output
  • IDE-specific files that vary between developers

This results in more accurate and contextual commit messages that focus on the actual code changes.

Configuration Methods

You can configure ignored files and extensions through multiple methods, following coco's configuration priority system:

1. Command Line Flags (Highest Priority)

# Ignore specific files
coco --ignored-files "package-lock.json" --ignored-files "dist/bundle.js"

# Ignore file extensions
coco --ignored-extensions ".map" --ignored-extensions ".min.js"

# Multiple values in one flag (comma-separated)
coco --ignored-files "*.lock,dist/*,build/*"

2. Project Configuration (.coco.config.json)

{
  "ignoredFiles": [
    "package-lock.json",
    "yarn.lock", 
    "pnpm-lock.yaml",
    "dist/bundle.js",
    "build/*"
  ],
  "ignoredExtensions": [
    ".map",
    ".lock",
    ".min.js",
    ".min.css"
  ]
}

3. Environment Variables

# Comma-separated values
export COCO_IGNORED_FILES="package-lock.json,yarn.lock,dist/*"
export COCO_IGNORED_EXTENSIONS=".map,.lock,.min.js"

4. Git Configuration

[coco]
    ignoredFiles = package-lock.json,yarn.lock,dist/*
    ignoredExtensions = .map,.lock,.min.js

Pattern Matching

coco uses the minimatch library for pattern matching, which supports glob patterns:

Basic Patterns

{
  "ignoredFiles": [
    "package-lock.json",           // Exact file name
    "*.lock",                      // All files ending with .lock
    "dist/*",                      // All files in dist directory
    "build/**/*",                  // All files in build directory and subdirectories
    "node_modules/**",             // Entire node_modules directory
    "coverage/lcov-report/*"       // All files in specific subdirectory
  ]
}

Advanced Patterns

{
  "ignoredFiles": [
    "**/*.{map,min.js,min.css}",   // Multiple extensions with brace expansion
    "src/**/*.test.{js,ts}",       // Test files in src directory
    "docs/{api,internal}/**",      // Multiple specific directories
    "*.{log,tmp,cache}",           // Multiple file types
    "!important-file.lock"         // Negation - don't ignore this specific file
  ]
}

Common Use Cases

Frontend Development

{
  "ignoredFiles": [
    "package-lock.json",
    "yarn.lock",
    "pnpm-lock.yaml",
    "dist/*",
    "build/*",
    "public/assets/*",
    ".next/*",
    ".nuxt/*",
    "coverage/*"
  ],
  "ignoredExtensions": [
    ".map",
    ".min.js",
    ".min.css",
    ".chunk.js",
    ".bundle.js"
  ]
}

Backend Development

{
  "ignoredFiles": [
    "Cargo.lock",
    "Gemfile.lock", 
    "composer.lock",
    "go.sum",
    "target/*",
    "vendor/*",
    "logs/*",
    "tmp/*"
  ],
  "ignoredExtensions": [
    ".log",
    ".tmp",
    ".cache",
    ".pid",
    ".sock"
  ]
}

Mobile Development

{
  "ignoredFiles": [
    "Podfile.lock",
    "ios/Pods/*",
    "android/build/*",
    "android/.gradle/*",
    "*.xcworkspace/*",
    "DerivedData/*"
  ],
  "ignoredExtensions": [
    ".dSYM",
    ".ipa",
    ".apk",
    ".aab"
  ]
}

Documentation Projects

{
  "ignoredFiles": [
    "_site/*",
    ".jekyll-cache/*",
    "node_modules/*",
    ".docusaurus/*",
    "build/*"
  ],
  "ignoredExtensions": [
    ".pdf",
    ".docx",
    ".pptx"
  ]
}

Default Configuration

coco comes with sensible defaults that cover common scenarios:

{
  "ignoredFiles": [
    "package-lock.json",
    // Contents of .gitignore file (automatically loaded)
    // Contents of .ignore file (automatically loaded)
  ],
  "ignoredExtensions": [
    ".map",
    ".lock"
  ]
}

Automatic .gitignore Integration

coco automatically reads and respects your .gitignore file, so files already ignored by git are also ignored by coco. This includes:

  • Files matching patterns in .gitignore
  • Files matching patterns in .ignore (if present)
  • Global gitignore patterns from your git configuration

Best Practices

1. Start with Defaults

Begin with the default configuration and add specific ignores as needed:

{
  "ignoredFiles": [
    // Keep defaults, add project-specific files
    "custom-generated-file.js",
    "project-specific-logs/*"
  ],
  "ignoredExtensions": [
    // Keep defaults, add project-specific extensions  
    ".generated",
    ".backup"
  ]
}

2. Use Specific Patterns

Be specific with your patterns to avoid accidentally ignoring important files:

{
  "ignoredFiles": [
    "dist/bundle.js",              // ✅ Specific file
    "dist/*"                       // ❌ Too broad, might ignore source maps you want
  ]
}

3. Document Team Conventions

Add comments to your configuration to explain team decisions:

{
  "ignoredFiles": [
    "package-lock.json",           // Standard npm lock file
    "docs/api-generated/*",        // Auto-generated API docs
    "src/types/generated.ts"       // Generated from GraphQL schema
  ]
}

4. Environment-Specific Ignores

Use environment variables for environment-specific ignores:

# Development environment
export COCO_IGNORED_FILES="debug.log,local-config.json"

# CI environment  
export COCO_IGNORED_FILES="test-results/*,coverage/*"

Testing Your Configuration

Verify Ignored Files

Use the --verbose flag to see which files are being processed:

# See which files coco is analyzing
coco --verbose commit

# Test with dry run (if available)
coco --verbose --dry-run commit

Debug Pattern Matching

Test your patterns using Node.js and minimatch:

const minimatch = require('minimatch')

// Test if a file matches your pattern
console.log(minimatch('dist/bundle.js', 'dist/*'))        // true
console.log(minimatch('src/index.js', 'dist/*'))          // false
console.log(minimatch('test.spec.js', '**/*.spec.js'))    // true

Troubleshooting

Common Issues

1. Pattern Not Working

# Check if your pattern syntax is correct
# Use double quotes for patterns with special characters
coco --ignored-files "**/*.{js,ts}.map"

2. Too Many Files Ignored

# Use more specific patterns
# Instead of: "src/*"
# Use: "src/generated/*"

3. Important Files Being Ignored

# Use negation patterns to include specific files
coco --ignored-files "*.lock" --ignored-files "!important.lock"

Debugging Commands

# See current configuration
coco init --scope project

# Verbose output shows file processing
coco --verbose commit

# Test specific patterns
node -e "console.log(require('minimatch')('your-file.js', 'your-pattern'))"

Advanced Configuration

Conditional Ignoring

Use different configurations for different scenarios:

{
  "ignoredFiles": [
    "package-lock.json"
  ],
  "ignoredExtensions": [
    ".map",
    ".lock"
  ]
}

Then override with environment variables:

# For feature branches, ignore test files
export COCO_IGNORED_FILES="**/*.test.js,**/*.spec.ts"

# For release branches, ignore documentation
export COCO_IGNORED_FILES="docs/*,README.md"

Integration with Build Tools

Configure ignores based on your build tool:

Webpack Projects:

{
  "ignoredFiles": [
    "webpack-stats.json",
    "dist/*",
    ".webpack/*"
  ]
}

Vite Projects:

{
  "ignoredFiles": [
    "dist/*",
    ".vite/*",
    "vite.config.*.timestamp-*"
  ]
}

Next.js Projects:

{
  "ignoredFiles": [
    ".next/*",
    "out/*",
    "next-env.d.ts"
  ]
}

Performance Considerations

Ignoring files can significantly improve coco's performance, especially in large repositories:

  • Large binary files: Always ignore to prevent memory issues
  • Generated directories: Ignore entire directories like node_modules, dist, build
  • Log files: Can be very large and change frequently
  • Cache directories: Usually not relevant for commit context
{
  "ignoredFiles": [
    "node_modules/**",             // Large directory
    "*.{jpg,png,gif,pdf}",         // Binary files
    "logs/**",                     // Log files
    ".cache/**"                    // Cache directories
  ]
}

This configuration helps coco focus on the files that matter most for generating meaningful commit messages while maintaining optimal performance.

Clone this wiki locally