django-linear-migrations 2.16.0

Adding new apps

When you add a new app to your project, you may need to create its max_migration.txt file to match any pre-created migrations. Add the new app to INSTALLED_APPS or FIRST_PARTY_APPS as appropriate, then rerun the creation command for the new app by specifying its label:

python manage.py create_max_migration_files my_new_app

Worked Example

Imagine you were working on your project’s books app in a feature branch called titles and created a migration called 0002_longer_titles. Meanwhile a commit has been merged to your main branch with a different 2nd migration for books called 0002_author_nicknames. Thanks to django-linear-migrations, the max_migration.txt file will show as conflicted between your feature and main branches.

Start the fix by reversing your new migration from your local database. This is necessary since it will be renamed after rebasing and seen as unapplied. Do this by switching to the feature branch titles migrating back to the last common migration:

$ git switch titles
$ python manage.py migrate books 0001

Then, fetch the latest code:

$ git switch main
$ git pull
...

Next, rebase your titles branch on top of it. During this process, Git will detect the conflict on max_migration.txt:

$ git switch titles
$ git rebase main
Auto-merging books/models.py
CONFLICT (content): Merge conflict in books/migrations/max_migration.txt
error: could not apply 123456789... Increase Book title length
Resolve all conflicts manually, mark them as resolved with
"git add/rm <conflicted_files>", then run "git rebase --continue".
You can instead skip this commit: run "git rebase --skip".
To abort and get back to the state before "git rebase", run "git rebase --abort".
Could not apply 123456789... Increase Book title length

The contents of the books app’s max_migration.txt at this point will look something like this:

$ cat books/migrations/max_migration.txt
<<<<<<< HEAD
0002_author_nicknames
=======
0002_longer_titles
>>>>>>> 123456789 (Increase Book title length)

At this point, use rebase_migration to automatically fix the books migration history:

$ python manage.py rebase_migration books
Renamed 0002_longer_titles.py to 0003_longer_titles.py, updated its dependencies, and updated max_migration.txt.

This places the conflicted migration on the end of the migration history. It renames the file appropriately, modifies its dependencies = [...] declaration, and updates the migration named in max_migration.txt appropriately.

After this, you should be able to continue the rebase:

$ git add books/migrations
$ git rebase --continue

And then migrate your local database to allow you to continue development:

$ python manage.py migrate books
Operations to perform:
  Target specific migration: 0003_longer_titles, from books
Running migrations:
  Applying books.0002_author_nicknames... OK
  Applying books.0003_longer_titles... OK

Code Formatting

rebase_migration does not guarantee that its edits match your code style. If you use a formatter like Black, you’ll want to run it after applying rebase_migration.

If you use pre-commit, note that Git does not invoke hooks during rebase commits. You can run it manually on changed files with pre-commit run.

Branches With Multiple Commits

Imagine the same example as above, but your feature branch has several commits editing the migration. This time, before rebasing onto the latest main branch, squash the commits in your feature branch together. This way, rebase_migration can edit the migration file when the conflict occurs.

You can do this with:

$ git rebase -i --keep-base main

This will open Git’s interactive mode file. Edit this so that every comit after the first will be squashed, by starting each line with “s”. Then close the file, and the rebase will execute.

After this operation, you can rebase onto your latest main branch as per the previous example.

Branches With Multiple Migrations

rebase_migration does not currently support rebasing multiple migrations (in the same app). This is an open feature request, but it is not a priority, since it’s generally a good idea to restrict changes to one migration at a time. Consider merging your migrations into one before rebasing.