3 files changed, 45 insertions, 12 deletions
diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index ce3a78f915..fedec7aefa 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -721,6 +721,19 @@ be warned that using ``--fake`` runs the risk of putting the migration state
 table into a state where manual recovery will be needed to make migrations
 run correctly.
 
+.. versionadded:: 1.8
+
+.. django-admin-option:: --fake-initial
+
+The ``--fake-initial`` option can be used to allow Django to skip an app's
+initial migration if all database tables with the names of all models created
+by all :class:`~django.db.migrations.operations.CreateModel` operations in that
+migration already exist. This option is intended for use when first running
+migrations against a database that preexisted the use of migrations. This
+option does not, however, check for matching database schema beyond matching
+table names and so is only safe to use if you are confident that your existing
+schema matches what is recorded in your initial migration.
+
 .. deprecated:: 1.8
 
     The ``--list`` option has been moved to the :djadmin:`showmigrations`
diff --git a/docs/releases/1.8.txt b/docs/releases/1.8.txt
index 4f77f063a3..4c7076a51e 100644
--- a/docs/releases/1.8.txt
+++ b/docs/releases/1.8.txt
@@ -1135,6 +1135,11 @@ Miscellaneous
   has been removed by a migration and replaced by a property. That means it's
   not possible to query or filter a ``ContentType`` by this field any longer.
 
+* :djadmin:`migrate` now accepts the :djadminopt:`--fake-initial` option to
+  allow faking initial migrations. In 1.7 initial migrations were always
+  automatically faked if all tables created in an initial migration already
+  existed.
+
 .. _deprecated-features-1.8:
 
 Features deprecated in 1.8
diff --git a/docs/topics/migrations.txt b/docs/topics/migrations.txt
index eaeb6da7c5..c1c14512c8 100644
--- a/docs/topics/migrations.txt
+++ b/docs/topics/migrations.txt
@@ -140,6 +140,13 @@ developers (or your production servers) check out the code, they'll
 get both the changes to your models and the accompanying migration at the
 same time.
 
+.. versionadded:: 1.8
+
+If you want to give the migration(s) a meaningful name instead of a generated
+one, you can use the :djadminopt:`--name` option::
+
+    $ python manage.py makemigrations --name changed_my_model your_app_label
+
 Version control
 ~~~~~~~~~~~~~~~
 
@@ -282,10 +289,12 @@ need to convert it to use migrations; this is a simple process::
 
     $ python manage.py makemigrations your_app_label
 
-This will make a new initial migration for your app. Now, when you run
-:djadmin:`migrate`, Django will detect that you have an initial migration
-*and* that the tables it wants to create already exist, and will mark the
-migration as already applied.
+This will make a new initial migration for your app. Now, run ``python
+manage.py migrate --fake-initial``, and Django will detect that you have an
+initial migration *and* that the tables it wants to create already exist, and
+will mark the migration as already applied. (Without the
+:djadminopt:`--fake-initial` flag, the :djadmin:`migrate` command would error
+out because the tables it wants to create already exist.)
 
 Note that this only works given two things:
 
@@ -297,12 +306,11 @@ Note that this only works given two things:
   that your database doesn't match your models, you'll just get errors when
   migrations try to modify those tables.
 
-.. versionadded:: 1.8
-
-If you want to give the migration(s) a meaningful name instead of a generated one,
-you can use the :djadminopt:`--name` option::
+.. versionchanged: 1.8
 
-    $ python manage.py makemigrations --name changed_my_model your_app_label
+    The ``--fake-initial`` flag to :djadmin:`migrate` was added. Previously,
+    Django would always automatically fake-apply initial migrations if it
+    detected that the tables exist.
 
 .. _historical-models:
 
@@ -706,9 +714,10 @@ If you already have pre-existing migrations created with
   ``__init__.py`` - make sure you remove the ``.pyc`` files too.
 * Run ``python manage.py makemigrations``. Django should see the empty
   migration directories and make new initial migrations in the new format.
-* Run ``python manage.py migrate``. Django will see that the tables for the
-  initial migrations already exist and mark them as applied without running
-  them.
+* Run ``python manage.py migrate --fake-initial``. Django will see that the
+  tables for the initial migrations already exist and mark them as applied
+  without running them. (Django won't check that the table schema match your
+  models, just that the right table names exist).
 
 That's it! The only complication is if you have a circular dependency loop
 of foreign keys; in this case, ``makemigrations`` might make more than one
@@ -716,6 +725,12 @@ initial migration, and you'll need to mark them all as applied using::
 
     python manage.py migrate --fake yourappnamehere
 
+.. versionchanged:: 1.8
+
+    The :djadminopt:`--fake-initial` flag was added to :djadmin:`migrate`;
+    previously, initial migrations were always automatically fake-applied if
+    existing tables were detected.
+
 Libraries/Third-party Apps
 ~~~~~~~~~~~~~~~~~~~~~~~~~~