Should Django Migration Files Be Added to .gitignore?

Django migration files track changes made to models and the database structure of a Django project. They allow reverting migrations and help teams stay in sync on a project’s database schema. However, migration files can often clutter version control history. So should they be added to .gitignore? There are good arguments on both sides.

The Case for Excluding Migration Files

There are a few reasons why adding Django migration files like to .gitignore makes sense:

1. Migration Files Can Clutter Commit History

Over the lifespan of a project, hundreds of migration files can accumulate. Tracking each file that often just alters a column or table name can create noisy commit logs. Ignoring migration files keeps the focus on more relevant application code changes in commits.

2. Different Developers Can Generate Conflicting Migrations

For example, suppose Developer A adds a model, then Developer B changes a field on the same model while pulling the first migration. Conflicting migrations that modify the same parts of a schema may occur. Excluding migration files relies on each developer generating fresh migrations in their environment, avoiding such merge conflicts.

In essence, migration files are a developer-specific detail. As long as the application models themselves are version controlled, each developer can rebuild migrations without conflicts.

3. It Encourages Periodically Resetting the Database

Since migration files produce database changes that depend on previous migrations, database schemas can sometimes get out of sync with models in confusing ways over time. Ignoring migration files promotes periodically wiping and rebuilding the production database from scratch via migrations. This cleans up inconsistencies.

So in summary, ignoring migration files like keeps version control leaner on database-related details between developers. It also prompts periodically resetting the database properly with python migrate.

Reasons for Version Controlling Migration Files

However, there are also good counter-arguments for making Django migrations a standard part of version control workflow:

1. Migration Files Provide Reproducibility

Having a sequence of numbered migration files allows reproducing any past database schema version exactly using python migrate <app_name> 0001. This can be important for handling legacy data or reproducing production database issues locally. LosingMigration files means losing this reproducibility.

2. They Provide Team Schema Knowledge

SeeingMigration files helps communicate schema history with a team. For example, if a column was renamed from product_name to product_title, having a RenameColumn migration captures this context plainly. Excluding files result in losing this useful context.

3. Migration Files Prevent Difficult-to-Debug Issues

For example, pulling model changes without corresponding migrations can sometimes corrupt database schemas in subtle ways. Keeping migrations under version control guards against hard-to-troubleshoot problems caused by sync differences between schemas and models.

So in other words, routinely version controllingMigration files helps document database schema history clearly over time for a team, preventing subtle issues that can occur otherwise.

BalancingMigration Files in Version Control

There are good-faith arguments on both sides here. How can a balance be struck, enjoying the main benefits of each approach?

Use .gitignore During Early Development

ExcludingMigration files from version control during early project stages keeps commits focused on application code first. After core models stabilize, migrations can be re-introduced with a fresh start, documenting final schemas in git.

Periodically Generate Fresh Migrations

Even with migrations under source control, periodically wiping the database and re-generating fresh migration files avoids major inconsistencies over time while retaining reproducibility. Think of migrations more as mile markers than permanent history.

ReviewMigration Files in Pull Requests

When reviewing model changes in pull requests, also scan generatedMigration files to check for odd or incorrect alterations. Reviewing migrations this way tests model/schema mapping logic.

Use a Migrations Documentation Tool

Services like Schema Migrations can independently track schema history over time with controls to update production safely. This provides benefits similar to source controlling migrations with more guards.


Django migration files allow smoothly evolving SQL database schemas alongside Django models over time. They provide powerful reproducibility, but can conflict between developers and clutter repositories.

The healthiest practices combine aspects of both philosophies: initially ignore migrations in early development, while reconsidering version controlling them at some point before launch depending on team preferences around reproducibility versus minimal commits. What matters most is that the production database schema tracks the true state of models in the application code. Following these balanced practices helps accomplish this effectively in a team environment.