Django Linear Migrations

2.19.0 · active · verified Sat Apr 11

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.

Warnings

breaking In version 2.0.0, the management commands were renamed from using hyphens to underscores to make them importable and extensible. `create-max-migration-files` became `create_max_migration_files` and `rebase-migration` became `rebase_migration`.
Fix: Update calls to the management commands (e.g., in CI scripts) to use the new underscore-separated names.
breaking As of version 2.19.0, support for Python 3.9 has been dropped. The library now requires Python 3.10 or newer.
Fix: Upgrade your Python environment to 3.10 or a later supported version.
gotcha Automatic detection of 'first-party' (project) apps can sometimes fail, especially with editable package installations (`pip install -e`). This can lead to `max_migration.txt` files being created for third-party apps.
Fix: 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', ...]`.
gotcha If you override Django's built-in `makemigrations` or `squashmigrations` commands in your project, your custom command must subclass the version provided by `django-linear-migrations` to ensure its functionality. Additionally, your app containing the custom command must be listed *above* `django_linear_migrations` in `INSTALLED_APPS`.
Fix: See the `imports` section for the correct subclassing pattern. Adjust `INSTALLED_APPS` order as necessary.
gotcha The `rebase_migration` command does not currently support rebasing multiple migrations within the same app. Attempting this may lead to unexpected behavior or incomplete rebasing.
Fix: 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`).
gotcha The `rebase_migration` command does not guarantee that its edits to migration files will match your project's code style. It will attempt to format with Black if installed, but manual reformatting may still be needed.
Fix: 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.

Install

pip install django-linear-migrations Install from PyPI

Imports

django_linear_migrations
```
INSTALLED_APPS = [
    # ...
    'django_linear_migrations',
    # ...
]
```
Add 'django_linear_migrations' to your Django project's INSTALLED_APPS setting.
Command
```
from django_linear_migrations.management.commands.makemigrations import Command as BaseCommand

class Command(BaseCommand):
    # ... your custom logic
    pass
```
When overriding Django's built-in `makemigrations` or `squashmigrations` with django-linear-migrations, your custom command must subclass `django_linear_migrations.management.commands.makemigrations.Command` (or `squashmigrations.Command`). Ensure your app with the custom command is listed *before* `django_linear_migrations` in `INSTALLED_APPS`.

Quickstart

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.

# 1. Install the library
pip install django-linear-migrations

# 2. Add to INSTALLED_APPS in settings.py
# settings.py
INSTALLED_APPS = [
    # ... your first-party apps first
    'your_app_name',
    'django_linear_migrations',
    # ... other third-party apps
]

# Optional: Explicitly define first-party apps if auto-detection fails (e.g., with editable installs)
# settings.py
# FIRST_PARTY_APPS = ['your_app_name']
# INSTALLED_APPS = FIRST_PARTY_APPS + ['django_linear_migrations', ...]

# 3. Check automatic detection of first-party apps (dry run)
python manage.py create_max_migration_files --dry-run

# 4. Create initial max_migration.txt files
python manage.py create_max_migration_files

# Now, makemigrations will automatically update max_migration.txt, 
# and `git rebase` or `git merge` will expose migration conflicts.

view raw JSON →