Black格式化工具中如何正确排除Django项目的migrations目录

在Django项目开发过程中，migrations目录下的文件是由Django自动生成的数据库迁移脚本。这些文件通常不需要进行代码格式化，因为它们的内容是由Django框架自动管理的。使用Black代码格式化工具时，如何正确排除这些目录是一个常见的配置问题。

问题现象

许多开发者在使用Black配合pre-commit时，发现尽管在配置文件中设置了exclude或extend-exclude参数来排除migrations目录，但这些迁移文件仍然会被格式化。这会导致每次提交时，自动生成的迁移文件被修改，可能引起不必要的版本控制冲突。

解决方案

Black提供了多种排除文件的方式，但需要注意它们的区别：

1. extend-exclude：这是最常用的排除方式，支持正则表达式匹配。对于Django项目，推荐使用以下配置：

[tool.black]
line-length = 88
extend-exclude = '''
/(
    | migrations
)/
'''

2. force-exclude：这是更严格的排除方式，会覆盖其他所有包含规则。如果上述方法无效，可以尝试：

[tool.black]
force-exclude = '''
/(
    | migrations
)/
'''

配置验证技巧

为了确认Black是否正确地识别了排除规则，可以使用-v参数运行Black查看详细输出：

black . -v

这将显示Black实际使用的配置，包括哪些文件被排除。在输出中应该能看到类似这样的信息：

src/utils/migrations ignored: matches the --extend-exclude regular expression

pre-commit的特殊注意事项

当通过pre-commit使用Black时，需要注意：

1. pre-commit会从项目根目录运行Black，因此相对路径的配置需要基于项目根目录
2. 可以在pre-commit配置中直接指定排除规则：

- repo: https://github.com/psf/black
  rev: 25.1.0
  hooks:
    - id: black
      exclude: migrations/

3. 确保没有其他pre-commit钩子或配置覆盖了Black的排除设置

最佳实践建议

1. 优先在pyproject.toml中配置排除规则，这样无论是直接运行Black还是通过pre-commit都能生效
2. 使用明确的路径模式，如/migrations/而不仅仅是migrations，以避免匹配到其他位置的同名目录
3. 对于大型项目，考虑将排除规则写得更加具体，例如/.*/migrations/来匹配所有应用下的migrations目录
4. 定期检查Black的版本更新，因为排除规则的处理方式可能会在版本更新中优化