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
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
skip_schemes_validation	--skip-schemes-validation / --no-skip-schemes-validation	Skip schemes validation
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.