From 29f1bd9953989630b7e7bcf558eccd7a765d42c8 Mon Sep 17 00:00:00 2001
From: Andy Wilkinson <awilkinson@pivotal.io>
Date: Wed, 19 Jul 2017 14:39:27 +0100
Subject: [PATCH] Make it clearer that default config locations are always used

Closes gh-4062
---
 .../main/asciidoc/spring-boot-features.adoc   | 33 ++++++++++++++-----
 1 file changed, 25 insertions(+), 8 deletions(-)

diff --git a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc
index e3464392c4..67ac7d3a83 100644
--- a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc
+++ b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc
@@ -551,14 +551,31 @@ being loaded, including profile-specific file names). Files specified in
 `spring.config.location` are used as-is, with no support for profile-specific variants,
 and will be overridden by any profile-specific properties.
 
-The default search path `classpath:,classpath:/config,file:,file:config/`
-is always used, irrespective of the value of `spring.config.location`. This search path
-is ordered from lowest to highest precedence (`file:config/` wins). If you do specify
-your own locations, they take precedence over all of the default locations and use the
-same lowest to highest precedence ordering. In that way you can set up default values for
-your application in `application.properties` (or whatever other basename you choose with
-`spring.config.name`) and override it at runtime with a different file, keeping the
-defaults.
+Config locations are searched in reverse order. By default, the configured locations are
+`classpath:/,classpath:/config/,file:./,file:./config/`. The resulting search order is:
+
+1. `file:./config/`
+2. `file:./`
+3. `classpath:/config/`
+4. `classpath:/`
+
+When custom config locations are configured, they are used in addition to the default
+locations. Custom locations are searched before the default locations. For example,
+if custom locations `classpath:/custom-config/,file:./custom-config/` are configured, the search order becomes:
+
+1. `file:./custom-config/`
+2. `classpath:custom-config/`
+3. `file:./config/`
+4. `file:./`
+5. `classpath:/config/`
+6. `classpath:/`
+
+This search ordering allows you to specify default values in one configuration file
+and then selectively override those values in another. You can provide default values
+for you application in `application.properties` (or whatever other basename you choose
+with `spring.config.name`) in one of the default locations. These default values can
+then be overriden at runtime with a different file located in one of the custom
+locations.
 
 NOTE: If you use environment variables rather than system properties, most operating
 systems disallow period-separated key names, but you can use underscores instead (e.g.