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)

bash

1# Ignore specific files
2coco commit --ignored-files "package-lock.json" --ignored-files "dist/bundle.js"
3
4# Ignore file extensions
5coco commit --ignored-extensions ".map" --ignored-extensions ".min.js"
6
7# Multiple values in one flag (comma-separated)
8coco commit --ignored-files "*.lock,dist/*,build/*"

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

json

1{
2  "ignoredFiles": [
3    "package-lock.json",
4    "yarn.lock", 
5    "pnpm-lock.yaml",
6    "dist/bundle.js",
7    "build/*"
8  ],
9  "ignoredExtensions": [
10    ".map",
11    ".lock",
12    ".min.js",
13    ".min.css"
14  ]
15}

3. Environment Variables

bash

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

4. Git Configuration

ini

[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

json

1{
2  "ignoredFiles": [
3    "package-lock.json",           // Exact file name
4    "*.lock",                      // All files ending with .lock
5    "dist/*",                      // All files in dist directory
6    "build/**/*",                  // All files in build directory and subdirectories
7    "node_modules/**",             // Entire node_modules directory
8    "coverage/lcov-report/*"       // All files in specific subdirectory
9  ]
10}

Advanced Patterns

json

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

Common Use Cases

Frontend Development

json

1{
2  "ignoredFiles": [
3    "package-lock.json",
4    "yarn.lock",
5    "pnpm-lock.yaml",
6    "dist/*",
7    "build/*",
8    "public/assets/*",
9    ".next/*",
10    ".nuxt/*",
11    "coverage/*"
12  ],
13  "ignoredExtensions": [
14    ".map",
15    ".min.js",
16    ".min.css",
17    ".chunk.js",
18    ".bundle.js"
19  ]
20}

Backend Development

json

1{
2  "ignoredFiles": [
3    "Cargo.lock",
4    "Gemfile.lock", 
5    "composer.lock",
6    "go.sum",
7    "target/*",
8    "vendor/*",
9    "logs/*",
10    "tmp/*"
11  ],
12  "ignoredExtensions": [
13    ".log",
14    ".tmp",
15    ".cache",
16    ".pid",
17    ".sock"
18  ]
19}

Mobile Development

json

1{
2  "ignoredFiles": [
3    "Podfile.lock",
4    "ios/Pods/*",
5    "android/build/*",
6    "android/.gradle/*",
7    "*.xcworkspace/*",
8    "DerivedData/*"
9  ],
10  "ignoredExtensions": [
11    ".dSYM",
12    ".ipa",
13    ".apk",
14    ".aab"
15  ]
16}

Documentation Projects

json

1{
2  "ignoredFiles": [
3    "_site/*",
4    ".jekyll-cache/*",
5    "node_modules/*",
6    ".docusaurus/*",
7    "build/*"
8  ],
9  "ignoredExtensions": [
10    ".pdf",
11    ".docx",
12    ".pptx"
13  ]
14}

Default Configuration

coco comes with sensible defaults that cover common scenarios:

json

1{
2  "ignoredFiles": [
3    "package-lock.json",
4    // Contents of .gitignore file (automatically loaded)
5    // Contents of .ignore file (automatically loaded)
6  ],
7  "ignoredExtensions": [
8    ".map",
9    ".lock"
10  ]
11}

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:

json

1{
2  "ignoredFiles": [
3    // Keep defaults, add project-specific files
4    "custom-generated-file.js",
5    "project-specific-logs/*"
6  ],
7  "ignoredExtensions": [
8    // Keep defaults, add project-specific extensions  
9    ".generated",
10    ".backup"
11  ]
12}

2. Use Specific Patterns

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

json

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

3. Document Team Conventions

Add comments to your configuration to explain team decisions:

json

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

4. Environment-Specific Ignores

Use environment variables for environment-specific ignores:

bash

1# Development environment
2export COCO_IGNORED_FILES="debug.log,local-config.json"
3
4# CI environment  
5export COCO_IGNORED_FILES="test-results/*,coverage/*"

Testing Your Configuration

Verify Ignored Files

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

bash

1# See which files coco is analyzing
2coco commit --verbose
3
4# Test with dry run (if available)
5coco commit --verbose --dry-run

Debug Pattern Matching

Test your patterns using Node.js and minimatch:

javascript

1const minimatch = require('minimatch')
2
3// Test if a file matches your pattern
4console.log(minimatch('dist/bundle.js', 'dist/*'))        // true
5console.log(minimatch('src/index.js', 'dist/*'))          // false
6console.log(minimatch('test.spec.js', '**/*.spec.js'))    // true

Troubleshooting

Common Issues

1. Pattern Not Working

bash

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

2. Too Many Files Ignored

bash

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

3. Important Files Being Ignored

bash

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

Debugging Commands

bash

1# See current configuration
2coco init --scope project
3
4# Verbose output shows file processing
5coco commit --verbose
6
7# Test specific patterns
8node -e "console.log(require('minimatch')('your-file.js', 'your-pattern'))"

Advanced Configuration

Conditional Ignoring

Use different configurations for different scenarios:

json

1{
2  "ignoredFiles": [
3    "package-lock.json"
4  ],
5  "ignoredExtensions": [
6    ".map",
7    ".lock"
8  ]
9}

Then override with environment variables:

bash

1# For feature branches, ignore test files
2export COCO_IGNORED_FILES="**/*.test.js,**/*.spec.ts"
3
4# For release branches, ignore documentation
5export COCO_IGNORED_FILES="docs/*,README.md"

Integration with Build Tools

Configure ignores based on your build tool:

Webpack Projects:

json

1{
2  "ignoredFiles": [
3    "webpack-stats.json",
4    "dist/*",
5    ".webpack/*"
6  ]
7}

Vite Projects:

json

1{
2  "ignoredFiles": [
3    "dist/*",
4    ".vite/*",
5    "vite.config.*.timestamp-*"
6  ]
7}

Next.js Projects:

json

1{
2  "ignoredFiles": [
3    ".next/*",
4    "out/*",
5    "next-env.d.ts"
6  ]
7}

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

json

1{
2  "ignoredFiles": [
3    "node_modules/**",             // Large directory
4    "*.{jpg,png,gif,pdf}",         // Binary files
5    "logs/**",                     // Log files
6    ".cache/**"                    // Cache directories
7  ]
8}

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

Why Ignore Files?

Configuration Methods

1. Command Line Flags (Highest Priority)

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

3. Environment Variables

4. Git Configuration

Pattern Matching

Basic Patterns

Advanced Patterns

Common Use Cases

Frontend Development

Backend Development

Mobile Development

Documentation Projects

Default Configuration

Automatic .gitignore Integration

Best Practices

1. Start with Defaults

2. Use Specific Patterns

3. Document Team Conventions

4. Environment-Specific Ignores

Testing Your Configuration

Verify Ignored Files

Debug Pattern Matching

Troubleshooting

Common Issues

Debugging Commands

Advanced Configuration

Conditional Ignoring

Integration with Build Tools

Performance Considerations

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