One common issue is when writing migrations in different git branches, you may get an error like:
FAILED: Multiple head revisions are present for given argument 'head'; please specify a specific target revision, '@head' to narrow to a specific head, or 'heads' for all heads
This basically means that you have more than one migration file which points to the same down_revision. That is, when you look at your migration file you should see some lines like the following, and there are multiple files with '4a4614932e00':
revision = '58f4a1203e80' down_revision = '4a4614932e00'
Thankfully it's an easy enough fix.
To automatically merge all heads, just run:
$ alembic merge heads
If you would like more control to merge specific heads together, run:
$ alembic merge -m "merge ae1 and 27c" ae1027 27c6a
For more info, check out the alembic documentation.