django-linear-migrations is a Django app that enforces a linear migration history in your project, preventing common issues caused by concurrent migration development and merge migrations. It achieves this by introducing `max_migration.txt` files for each app, which will conflict in version control (e.g., Git) if multiple branches add migrations concurrently. The library, currently at version 2.19.0, is actively maintained with frequent releases.
pip install django-linear-migrationsVerified import paths — ran on the pinned version, not inferred.
After installation, add `django_linear_migrations` to your `INSTALLED_APPS`. Run `create_max_migration_files --dry-run` to verify first-party app detection, then run `create_max_migration_files` to generate `max_migration.txt` files for your apps. These files track the latest migration and will cause Git conflicts if new migrations are created on divergent branches, forcing a linear history. The `rebase_migration` command can help resolve these conflicts automatically.
Update calls to the management commands (e.g., in CI scripts) to use the new underscore-separated names.
Upgrade your Python environment to 3.10 or a later supported version.
Explicitly define your first-party apps using the `FIRST_PARTY_APPS` setting in your `settings.py`. For example: `FIRST_PARTY_APPS = ['your_app_name', 'another_app']` and combine it into `INSTALLED_APPS`: `INSTALLED_APPS = FIRST_PARTY_APPS + ['django_linear_migrations', ...]`.
See the `imports` section for the correct subclassing pattern. Adjust `INSTALLED_APPS` order as necessary.
If your feature branch has multiple commits that create migrations, it's recommended to squash those commits into a single migration before rebasing your branch onto the main branch (e.g., using `git rebase -i --keep-base main`).
After running `python manage.py rebase_migration <app_label>`, run your code formatter (e.g., Black, isort) on the modified migration files. If you use pre-commit hooks, remember that Git does not invoke hooks during rebase commits, so you might need to run `pre-commit run` manually on the changed files.
Rebase your feature branch onto the main branch, resolve the `max_migration.txt` conflict by accepting the incoming change, and then run `python manage.py rebase_migration <app_label>` to re-order your local migration and update the `max_migration.txt` file correctly.
Manually update the `max_migration.txt` file to contain the exact name of the latest migration file, or run `python manage.py create_max_migration_files --recreate <app_label>` to automatically regenerate it.
For first-party apps managed by `django-linear-migrations`, use `python manage.py rebase_migration <app_label>` to resolve the conflict. For complex cases or third-party apps, manually inspect migration dependencies and consider squashing migrations or resetting migration history in a development environment.
Explicitly define your first-party apps by setting `FIRST_PARTY_APPS = ['your_app_name', 'another_app']` in your `settings.py` and ensure `INSTALLED_APPS = FIRST_PARTY_APPS + ['django_linear_migrations', ...]` to prevent files from being created for unintended apps.