Sharing StyleCop Settings Across Projects
By default, StyleCop configuration settings are applied on a project by project basis. In a standard installation, each project folder will contain a Settings.SourceAnalysis file, describing the settings for this project. In cases where the default settings are used, there may be no settings file for the project.
It is possible, however, to create StyleCop settings files which apply to more than one project, or which can apply to all projects within your source code tree. This is accomplished through the use of parent settings files.
Parent Settings Files
The idea behind parent settings files is simple. Settings within StyleCop settings files apply to all projects located in all subdirectories beneath the location of the settings file. Place a Settings.SourceAnalysis file in any root directory, and it will automatically apply to all projects beneath that directory.
When using a parent settings file, it is still possible to configure settings for an individual project. In fact, any settings set on an individual project will override any settings specified in a parent settings file.
It is also possible to chain multiple settings files together. For example, consider a fictional company that places a settings file at the root of its source tree. Within this settings file, a small handful of rules are disabled. These settings will apply to all projects, since the file sits at the root directory.
The test team within this company wants to disable a few more rules for all test code. Luckily, all of the test code is placed beneath a Test subdirectory. The test team places another Settings.SourceAnalysis file within the Test folder. All test projects will now read both the test settings file and the root settings file, and the settings from both of these files will be merged together and applied.
Within this same company, one tester believes that his code is ultra-critical, and wants to turn on more of the rules for that code. He creates a settings file for his own project, and overrides some of the settings in the parent settings files by re-enabling a few of the rules that were previously disabled. These settings only apply to his project, since this settings file is sitting within the root of his project directory.
This is the basic concept behind settings files in StyleCop. Using parent settings files is an easy and efficient way to apply settings globaly across your entire codebase, or across portions of that codebase.
Global Settings File
The parent settings file concept extends even beyond the root of your source tree. Another StyleCop settings file can be placed within the StyleCop installation folder. This is the same folder that contains Microsoft.SourceAnalysis.dll. A settings file placed within this folder will be considered the ultimate parent settings file, and settings within this file will apply to all projects analyzed by StyleCop, no matter where they are located.
Ignoring Parent Settings Files
In some situations, it is desirable to ignore any settings files above a particular directory. For example, consider the fictional company described above, with a settings file at the root, a settings file within the test folder, and a settings file at the project level. It might turn out that the test organization does not want to use any of the settings within the root settings file, but wants to set things up completely differently. This might be troublesome, since all of the test code is located within a Test folder, which is itself located beneath the root folder containing the root settings file. By default, all test code will pick up settings from the root settings file.
It is possible at any level of the source tree to set a flag indicating that parent settings files above that point should be ignored completely. This is done by configuring the settings on the Settings Files tab within the settings dialog:
By default, the "Merge with settings file found in parent folders" option is selected. StyleCop will continue searching above the current directory for additional parent settings files. Clicking the Edit button next to this option will cause StyleCop to open the settings dialog for the next parent settings file, if there is one.
If StyleCop should stop looking for additional settings files above the current directory, select the "Do not merge with any other settings files" option, and click ok.
Linking To A Settings File
Rather than merging with a settings file found within a parent directory, it is also possible to provide an explicit link to another settings file to merge with. This is accomplished by selecting the "Merge with the following settings file" option, and then providing the path to another settings file. The path can contain environment variables, if needed. For example:
It is possible to click the Edit button next to the linked settings file path to edit that settings file.
Overriding Parent Settings
Whenever a settings file overrides settings specified in a parent settings file, the overriden settings are shown in bold within the settings dialog. For example:
