Configuration

Once you’ve settled upon the appropriate options for your project, you can persist them in a YAML configuration file instead of passing them on every invocation.

Periphery looks for .periphery.yml in the current directory. Pass --config <path> to use a file elsewhere.

The quickest way to produce one is to run a scan with --verbose. Near the beginning of the output you’ll see a [configuration:begin] section containing your current options formatted as YAML. Copy it into .periphery.yml, and you can then simply run periphery scan.

project: MyProject.xcodeproj
schemes:
  - MyScheme
exclude_tests: true
retain_public: true
report_exclude:
  - "**/Generated/*.swift"

Command-line options take precedence over values in the configuration file.

Options

Configuration keys use snake_case, while command-line options use kebab-case. The table below is generated from the configurable options in ScanCommand.swift during the website build.

Configuration key	Command-line option	Description
build_arguments	arguments after --	Arguments following ‘–’ will be passed to the underlying build tool, which is either ‘swift build’ or ‘xcodebuild’ depending on your project. Values containing whitespace or shell metacharacters must be quoted, e.g. OTHER_SWIFT_FLAGS=‘$(inherited) -no-warnings-as-errors’. Already-quoted values are preserved as passed
project	--project	Path to your project’s .xcodeproj or .xcworkspace
schemes	--schemes	Schemes to build. All targets built by these schemes will be scanned
format	--format	Output format
exclude_tests	--exclude-tests	Exclude test targets from indexing
exclude_targets	--exclude-targets	Targets to exclude from indexing
index_exclude	--index-exclude	Source file globs to exclude from indexing
report_exclude	--report-exclude	Source file globs to exclude from the results. Note that this option is purely cosmetic, these files will still be indexed
report_include	--report-include	Source file globs to include in the results. This option supersedes ‘–report-exclude’. Note that this option is purely cosmetic, these files will still be indexed
retain_files	--retain-files	Source file globs for which all containing declarations will be retained
index_store_path	--index-store-path	Index store paths. Implies ‘–skip-build’
retain_public	--retain-public	Retain all public declarations, recommended for framework/library projects
no_retain_spi	--no-retain-spi	Public SPIs (System Programming Interfaces) to check for unused code even when ‘–retain-public’ is enabled
disable_redundant_public_analysis	--disable-redundant-public-analysis	Disable identification of redundant public accessibility
disable_unused_import_analysis	--disable-unused-import-analysis	Disable identification of unused imports
superfluous_ignore_comments	--superfluous-ignore-comments / --no-superfluous-ignore-comments	Report superfluous ignore comments
retain_unused_imported_modules	--retain-unused-imported-modules	Names of unused imported modules to retain
retain_assign_only_properties	--retain-assign-only-properties	Retain properties that are assigned, but never used
retain_assign_only_property_types	--retain-assign-only-property-types	Property types to retain if the property is assigned, but never read
external_encodable_protocols	--external-encodable-protocols	Names of external protocols that inherit Encodable. Properties and CodingKey enums of types conforming to these protocols will be retained
external_codable_protocols	--external-codable-protocols	Names of external protocols that inherit Codable. Properties and CodingKey enums of types conforming to these protocols will be retained
external_test_case_classes	--external-test-case-classes	Names of XCTestCase subclasses that reside in external targets
retain_objc_accessible	--retain-objc-accessible	Retain declarations that are exposed to Objective-C implicitly by inheriting NSObject classes, or explicitly with the @objc and @objcMembers attributes
retain_objc_annotated	--retain-objc-annotated	Retain declarations that are exposed to Objective-C explicitly with the @objc and @objcMembers attributes
retain_unused_protocol_func_params	--retain-unused-protocol-func-params	Retain unused protocol function parameters, even if the parameter is unused in all conforming functions
retain_swift_ui_previews	--retain-swift-ui-previews	Retain SwiftUI previews
retain_codable_properties	--retain-codable-properties	Retain properties on Codable types (including Encodable and Decodable)
retain_encodable_properties	--retain-encodable-properties	Retain properties on Encodable types only
retain_equatable_properties	--retain-equatable-properties	Retain properties on Equatable types, including Hashable types
retain_hashable_properties	--retain-hashable-properties	Retain properties on Hashable types
clean_build	--clean-build	Clean existing build artifacts before building
skip_build	--skip-build	Skip the project build step
relative_results	--relative-results	Output result paths relative to the current directory
strict	--strict	Exit with non-zero status if any unused code is found
disable_update_check	--disable-update-check	Disable checking for updates
verbose	--verbose	Enable verbose logging
quiet	--quiet	Only output results
color	--color	Colored output mode
json_package_manifest_path	--json-package-manifest-path	JSON package manifest path (obtained using swift package describe --type json or manually)
baseline	--baseline	Baseline file path used to filter results
write_baseline	--write-baseline	Baseline file path where results are written. Pass the same path to ‘–baseline’ in subsequent scans to exclude the results recorded in the baseline.
write_results	--write-results	File path where formatted results are written.
generic_project_config	--generic-project-config	Project configuration for non-Apple build systems

Bazel configuration is handled by rules_periphery, rather than Periphery’s YAML configuration.