Fixed #26975 -- Clarified how Django looks for fixture files.

Co-Authored-By: Daniel Brotsky <dev@brotsky.com>

1 files changed, 26 insertions, 13 deletions

diff --git a/docs/howto/initial-data.txt b/docs/howto/initial-data.txt
index 7a43196957..08c55e1114 100644
--- a/docs/howto/initial-data.txt
+++ b/docs/howto/initial-data.txt
@@ -6,18 +6,18 @@ It's sometimes useful to prepopulate your database with hard-coded data when
 you're first setting up an app. You can provide initial data with migrations or
 fixtures.
 
-Providing initial data with migrations
-======================================
+Provide initial data with migrations
+====================================
 
-If you want to automatically load initial data for an app, create a
+To automatically load initial data for an app, create a
 :ref:`data migration <data-migrations>`. Migrations are run when setting up the
 test database, so the data will be available there, subject to :ref:`some
 limitations <test-case-serialized-rollback>`.
 
 .. _initial-data-via-fixtures:
 
-Providing data with fixtures
-============================
+Provide data with fixtures
+==========================
 
 You can also provide data using fixtures, however, this data isn't loaded
 automatically, except if you use :attr:`.TransactionTestCase.fixtures`.
@@ -80,16 +80,29 @@ from the fixture and reloaded into the database. Note this means that if you
 change one of the rows created by a fixture and then run :djadmin:`loaddata`
 again, you'll wipe out any changes you've made.
 
-Where Django finds fixture files
---------------------------------
+Tell Django where to look for fixture files
+-------------------------------------------
+
+By default, Django looks for fixtures in the ``fixtures`` directory inside each
+app for, so the command ``loaddata sample`` will find the file
+``my_app/fixtures/sample.json``. This works with relative paths as well, so
+``loaddata my_app/sample`` will find the file
+``my_app/fixtures/my_app/sample.json``.
+
+Django also looks for fixtures in the list of directories provided in the
+:setting:`FIXTURE_DIRS` setting.
+
+To completely prevent default search form happening, use an absolute path to
+specify the location of your fixture file, e.g. ``loaddata /path/to/sample``.
 
-By default, Django looks in the ``fixtures`` directory inside each app for
-fixtures. You can set the :setting:`FIXTURE_DIRS` setting to a list of
-additional directories where Django should look.
+.. admonition:: Namespace your fixture files
 
-When running :djadmin:`manage.py loaddata <loaddata>`, you can also
-specify a path to a fixture file, which overrides searching the usual
-directories.
+    Django will use the first fixture file it finds whose name matches, so if
+    you have fixture files with the same name in different applications, you
+    will be unable to distinguish between them in your ``loaddata`` commands.
+    The easiest way to avoid this problem is by *namespacing* your fixture
+    files. That is, by putting them inside a directory named for their
+    application, as in the relative path example above.
 
 .. seealso::