squash! Add support for $XDG_CONFIG_HOME/rspec/options

XDG config file completely overrides HOME file.

Author: Mange

features/configuration/default_path.feature

@@ -5,8 +5,7 @@ Feature: Setting the default spec path
   This is supported by a `--default-path` option, which is set to `spec` by
   default. If you prefer to keep your specs in a different directory, or assign
   an individual file to `--default-path`, you can do so on the command line or
-  in a configuration file (`.rspec`, `~/.rspec`,
-  `$XDG_CONFIG_HOME/rspec/options`, or a custom file).
+  in a configuration file (for example `.rspec`).
 
   **NOTE:** this option is not supported on `RSpec.configuration`, as it needs to be
   set before spec files are loaded.

features/configuration/read_options_from_file.feature

@@ -1,26 +1,32 @@
 Feature: read command line configuration options from files
 
-  RSpec reads command line configuration options from files in three different
-  locations:
+  RSpec reads command line configuration options from several different files,
+  all conforming to a specific level of specificity. Options from a higher
+  specificity will override conflicting options from lower specificity files.
 
-    * Local: `./.rspec-local` (i.e. in the project's root directory, can be
-      gitignored)
+  The locations are:
+
+    * **Global options:** First file from the following list (i.e. the user's
+      personal global options)
 
-    * Project:  `./.rspec` (i.e. in the project's root directory, usually
+      * `$XDG_CONFIG_HOME/rspec/options` ([XDG Base Directory
+        Specification](https://specifications.freedesktop.org/basedir-spec/latest/)
+        config)
+      * `~/.rspec`
+
+    * **Project options:**  `./.rspec` (i.e. in the project's root directory, usually
       checked into the project)
 
-    * Global (HOME): `~/.rspec` (i.e. in the user's home directory)
+    * **Local:** `./.rspec-local` (i.e. in the project's root directory, can be
+      gitignored)
 
-    * Global (XDG): `$XDG_CONFIG_HOME/rspec/options` (i.e. in the user's
-      [the XDG Base Directory
-      Specification](https://specifications.freedesktop.org/basedir-spec/latest/)
-      config directory)
+  Options specified at the command-line has even higher specificity, as does
+  the `SPEC_OPTS` environment variable. That means that a command-line option
+  would overwrite a project-specific option, which overrides the global value
+  of that option.
 
-  Configuration options are loaded from `$XDG_CONFIG_HOME/rspec/options`,
-  `~/.rspec`, `.rspec`, `.rspec-local`, command line switches, and the
-  `SPEC_OPTS` environment variable (listed in lowest to highest precedence; for
-  example, an option in `~/.rspec` can be overridden by an option in
-  `.rspec-local`).
+  The default options files can all be ignored using the `--options`
+  command-line argument, which selects a custom file to load options from.
 
   Scenario: Color set in `.rspec`
     Given a file named ".rspec" with:

lib/rspec/core/configuration.rb

@@ -9,11 +9,24 @@ module Core
 
     # Stores runtime configuration information.
     #
-    # Configuration options are loaded from `$XDG_CONFIG_HOME/rspec/options`,
-    # `~/.rspec`, `.rspec`, `.rspec-local`, command line switches, and the
-    # `SPEC_OPTS` environment variable (listed in lowest to highest precedence;
-    # for example, an option in `~/.rspec` can be overridden by an option in
-    # `.rspec-local`).
+    # Configuration options are loaded from multiple files and joined together
+    # with command-line switches and the `SPEC_OPTS` environment variable.
+    #
+    # Precedence order (where later entries overwrite earlier entries on
+    # conflicts):
+    #
+    #   * Global (`$XDG_CONFIG_HOME/rspec/options`, or `~/.rspec` if it does
+    #     not exist)
+    #   * Project-specific (`./.rspec`)
+    #   * Local (`./.rspec-local`)
+    #   * Command-line options
+    #   * `SPEC_OPTS`
+    #
+    # For example, an option set in the local file will override an option set
+    # in your global file.
+    #
+    # The global, project-specific and local files can all be overridden with a
+    # separate custom file using the --options command-line parameter.
     #
     # @example Standard settings
     #     RSpec.configure do |c|

lib/rspec/core/configuration_options.rb

@@ -122,7 +122,7 @@ def file_options
         if custom_options_file
           [custom_options]
         else
-          [global_xdg_options, global_options, project_options, local_options]
+          [global_options, project_options, local_options]
         end
       end
 
@@ -155,10 +155,6 @@ def global_options
         @global_options ||= options_from(global_options_file)
       end
 
-      def global_xdg_options
-        @global_xdg_options ||= options_from(global_xdg_options_file)
-      end
-
       def options_from(path)
         args = args_from_options_file(path)
         parse_args_ignoring_files_or_dirs_to_run(args, path)
@@ -197,6 +193,17 @@ def local_options_file
       end
 
       def global_options_file
+        xdg_options_file_if_exists || home_options_file_path
+      end
+
+      def xdg_options_file_if_exists
+        path = xdg_options_file_path
+        if path && File.exist?(path)
+          path
+        end
+      end
+
+      def home_options_file_path
         File.join(File.expand_path("~"), ".rspec")
       rescue ArgumentError
         # :nocov:
@@ -205,7 +212,7 @@ def global_options_file
         # :nocov:
       end
 
-      def global_xdg_options_file
+      def xdg_options_file_path
         xdg_config_home = resolve_xdg_config_home
         if xdg_config_home
           File.join(xdg_config_home, "rspec", "options")

spec/rspec/core/configuration_options_spec.rb

@@ -456,15 +456,36 @@ def expect_parsing_to_fail_mentioning_source(source, options=[])
       create_fixture_file("~/.config/rspec/options", "--order defined")
       with_env_vars 'SPEC_OPTS' => "--example 'foo bar'" do
         options = parse_options("--drb")
-        expect(options[:color_mode]).to eq(:on)
+        # $XDG_CONFIG_HOME/rspec/options file ("order") is read, but ~/.rspec
+        # file ("color") is not read because ~/.rspec has lower priority over
+        # the file in the XDG config directory.
+        expect(options[:order]).to eq("defined")
+        expect(options[:color_mode]).to be_nil
+
         expect(options[:requires]).to eq(["some_file"])
         expect(options[:full_description]).to eq([/foo\ bar/])
         expect(options[:drb]).to be_truthy
         expect(options[:formatters]).to eq([['global']])
-        expect(options[:order]).to eq("defined")
       end
     end
 
+    it "reads ~/.rspec if $XDG_CONFIG_HOME/rspec/options is not found" do
+      create_fixture_file("~/.rspec", "--force-color")
+
+      options = parse_options()
+      expect(options[:color_mode]).to eq(:on)
+      expect(options[:order]).to be_nil
+    end
+
+    it "does not read ~/.rspec if $XDG_CONFIG_HOME/rspec/options is present" do
+      create_fixture_file("~/.rspec", "--force-color")
+      create_fixture_file("~/.config/rspec/options", "--order defined")
+
+      options = parse_options()
+      expect(options[:color_mode]).to be_nil
+      expect(options[:order]).to eq("defined")
+    end
+
     it "uses $XDG_CONFIG_HOME environment variable when set to find XDG global options" do
       create_fixture_file("~/.config/rspec/options", "--format default_xdg")
       create_fixture_file("~/.custom-config/rspec/options", "--format overridden_xdg")

spec/support/isolated_home_directory.rb

@@ -5,8 +5,9 @@
 RSpec.shared_context "isolated home directory" do
   around do |ex|
     Dir.mktmpdir do |tmp_dir|
-      # If user has a custom $XDG_CONFIG_HOME, also clear that out when
-      # changing $HOME so tests don't touch the user's real config files.
+      # If user running this test suite has a custom $XDG_CONFIG_HOME, also
+      # clear that out when changing $HOME so tests don't touch the user's real
+      # configuration files.
       without_env_vars "XDG_CONFIG_HOME" do
         with_env_vars "HOME" => tmp_dir do
           ex.call