Options

Every option of the scan command, with its key in the configuration file, its type and its default. Run outskirts help scan for the help of your version, and see Configuration for how the command line and the file combine.

• Every option that takes no value, except --setup and --skip-stdout-results, also has a --no- form, e.g. --no-strict.
• Options that take a list accept several values after one flag, e.g. --exclude-targets A B; in the file, a single value is read as a list of one.
• Relative paths are resolved from --project-root.

This page is generated from outskirts.schema.json, itself generated by outskirts config schema.

Command line only#

--setup#

Guided setup: detects the project type, asks a few questions, then prints and runs the full scan command. Run it at the project root.

See Configuration: Command line and file.

--project-root#

Root directory of the project, from which relative paths are resolved. Default: the current directory.

See Configuration: The configuration file, Configuration: Command line and file, Configuration: Paths, Baselines: Options.

--config#

Configuration file. A relative path is resolved from --project-root. Default: .outskirts.yml, else .periphery.yml, in the project root.

See Configuration: The configuration file, Configuration: Command line and file, Configuration: Paths.

Project and build#

--project#

Path to the .xcodeproj or .xcworkspace.

Key project · string · default none.

--schemes#

Schemes to build; every target they build is scanned.

Key schemes · list of strings · default empty.

See Getting started: How a scan works, Troubleshooting: A declaration used only by a target that was not built.

-- <args>#

Arguments passed to the underlying build tool (swift build or xcodebuild).

Key build_arguments · list of strings · default empty.

See Migrating from Periphery: What changed since Periphery 3.x.

xcode_list_arguments#

Extra arguments for the 'xcodebuild -list' call that lists schemes (guided setup).

Key xcode_list_arguments · configuration file only · list of strings · default empty.

See Migrating from Periphery: What changed since Periphery 3.x, Configuration: Command line and file.

--clean-build#

Remove existing build artifacts before building.

Key clean_build · flag, --no-clean-build to switch off · default false.

See Troubleshooting: Results in the wrong place or false positives in one file, Credits: External contributions.

--skip-build#

Skip the project build step.

Key skip_build · flag, --no-skip-build to switch off · default false.

See Getting started: How a scan works, Getting started: Xcode projects, Continuous integration: Reusing the build, Continuous integration: GitHub Actions.

--skip-schemes-validation#

Do not check that the schemes exist.

Key skip_schemes_validation · flag, --no-skip-schemes-validation to switch off · default false.

--index-store-path#

Index store paths, relative to the project root; implies skip_build.

Key index_store_path · list of strings · default empty.

See Getting started: Swift packages, Getting started: Xcode projects, Configuration: Paths, Continuous integration: Reusing the build.

--json-package-manifest-path#

Package manifest as JSON (from 'swift package describe --type json', or written by hand).

Key json_package_manifest_path · string · default none.

See Configuration: Paths.

--generic-project-config#

Project configuration file for other build systems.

Key generic_project_config · string · default none.

See Configuration: Paths.

--cache-max-age-days#

Age in days after which unused Xcode build caches are evicted at the end of a scan; 0 disables eviction.

Key cache_max_age_days · integer · default 14.

See Getting started: How a scan works.

Files and scope#

--exclude-targets#

Targets to exclude from indexing.

Key exclude_targets · list of strings · default empty.

See Excluding files: Excluding indexed files, Configuration: Validation.

--exclude-tests#

Exclude test targets from indexing.

Key exclude_tests · flag, --no-exclude-tests to switch off · default false.

See Analysis: Literal matching, Excluding files: Excluding indexed files.

--index-exclude#

Source file globs to leave out of indexing, added to the default ones.

Key index_exclude · list of strings · default **/*?.build/**/*, **/SourcePackages/checkouts/**.

See Analysis: Asset catalog colors, Analysis: Metal functions, Framework conventions and retention: Protobuf, Excluding files: Excluding indexed files.

--report-exclude#

Source file globs to leave out of the results, optionally per result kind with '<glob>:kind1,kind2' or {path, kinds}; the files are still indexed.

Key report_exclude · list of strings · default empty.

See Getting started: How a scan works, Analysis: Asset catalog colors, Analysis: Asset catalog images, Excluding files.

--report-include#

Source file globs to keep in the results; supersedes report_exclude; the other files are still indexed.

Key report_include · list of strings · default empty.

See Excluding files: Including results, Continuous integration: Pull request checks, Configuration: Paths, Baselines: Baseline ratchet.

--retain-files#

Source file globs for which all containing declarations are retained.

Key retain_files · list of strings · default empty.

See Framework conventions and retention, Comment commands: Ignore a whole file, Excluding files: Retaining file declarations, Configuration: Paths.

--changed-since#

Report only the results in files that changed since this git ref: committed since its merge base with HEAD, uncommitted or untracked. The whole project is still analysed.

Key changed_since · string · default none.

See Baselines: Baselines and pull requests, Roadmap: Published.

--changed-lines#

With changed_since, report only the results on changed lines.

Key changed_lines · flag, --no-changed-lines to switch off · default false.

See Continuous integration: Pull request checks, Roadmap: Published.

Analyses#

--disable-redundant-public-analysis#

Disable identification of redundant public accessibility.

Key disable_redundant_public_analysis · flag, --no-disable-redundant-public-analysis to switch off · default false.

See Analysis: Redundant public accessibility.

--enable-redundant-public-members#

Also find redundant public accessibility on the members of public types and extensions.

Key enable_redundant_public_members · flag, --no-enable-redundant-public-members to switch off · default false.

See Analysis: Public members.

--enable-open-final-analysis#

Find redundant open accessibility and classes or members that could be final.

Key enable_open_final_analysis · flag, --no-enable-open-final-analysis to switch off · default false.

See Analysis: Result kinds, Analysis: Open and final.

--enable-empty-extension-analysis#

Find extensions that declare no member and no conformance.

Key enable_empty_extension_analysis · flag, --no-enable-empty-extension-analysis to switch off · default false.

See Analysis: Result kinds, Analysis: Empty extensions.

--enable-redundant-access-level-analysis#

Find access modifiers identical to the default of their enclosing context.

Key enable_redundant_access_level_analysis · flag, --no-enable-redundant-access-level-analysis to switch off · default false.

See Analysis: Result kinds, Analysis: Redundant access levels.

--report-unused-type-parameters#

Also report unused generic parameters of types, ignored by default as they may be phantom types.

Key report_unused_type_parameters · flag, --no-report-unused-type-parameters to switch off · default false.

See Analysis: Generic type parameters, Roadmap: Published.

--enable-unassigned-optional-analysis#

Find optional properties that are read but never assigned (always nil).

Key enable_unassigned_optional_analysis · flag, --no-enable-unassigned-optional-analysis to switch off · default false.

See Analysis: Result kinds, Analysis: Unassigned optional properties.

--disable-unused-import-analysis#

Turn off the analysis of unused imports.

Key disable_unused_import_analysis · flag, --no-disable-unused-import-analysis to switch off · default false.

See Analysis: Unused imports, Analysis: Mixed Swift and Objective-C targets.

--enable-unused-system-imports#

Also analyze imports of system frameworks (experimental).

Key enable_unused_system_imports · flag, --no-enable-unused-system-imports to switch off · default false.

See Analysis: System framework imports, Framework conventions and retention: Platform conditionals.

--superfluous-ignore-comments#

Report ignore comments that ignore nothing.

Key superfluous_ignore_comments · flag, --no-superfluous-ignore-comments to switch off · default true.

See Analysis: Superfluous ignore comments.

--disable-platform-conditional-retention#

Do not retain declarations unavailable on a platform or referenced from platform conditional compilation blocks.

Key disable_platform_conditional_retention · flag, --no-disable-platform-conditional-retention to switch off · default false.

See Framework conventions and retention: Platform conditionals.

--detect-unused-asset-catalog-colors#

Find unused colors of Xcode asset catalogs.

Key detect_unused_asset_catalog_colors · flag, --no-detect-unused-asset-catalog-colors to switch off · default false.

See Analysis: Result kinds, Analysis: Asset catalog colors.

--detect-unused-asset-catalog-images#

Find unused images of Xcode asset catalogs.

Key detect_unused_asset_catalog_images · flag, --no-detect-unused-asset-catalog-images to switch off · default false.

See Analysis: Result kinds, Analysis: Asset catalog images.

--detect-unused-metal-functions#

Find Metal functions that no Swift string literal names, and literals naming a Metal function that no .metal file declares.

Key detect_unused_metal_functions · flag, --no-detect-unused-metal-functions to switch off · default false.

See Analysis: Result kinds, Analysis: Metal functions, Roadmap: Published.

Localized strings#

--disable-unused-localized-string-analysis#

Turn off the analysis of unused String Catalog (xcstrings) keys.

Key disable_unused_localized_string_analysis · flag, --no-disable-unused-localized-string-analysis to switch off · default false.

See Analysis: Unused localized strings.

--localized-string-catalog-exclude#

String Catalog globs left out of the localized strings analysis.

Key localized_string_catalog_exclude · list of strings · default **/InfoPlist.xcstrings, **/AppShortcuts.xcstrings.

See Analysis: Excluding catalogues, Excluding files: String Catalogs, Analysis: Literal matching.

--localized-string-key-patterns#

Key patterns (globs, or regular expressions between slashes) of keys used dynamically, retained from String Catalogs.

Key localized_string_key_patterns · list of strings · default empty.

See Analysis: Key patterns, Analysis: Keys built at runtime, Analysis: Literal matching.

--localized-string-key-literal-match#

Retain localized string keys equal to any string literal of the source.

Key localized_string_key_literal_match · flag, --no-localized-string-key-literal-match to switch off · default false.

See Analysis: Literal matching.

--retain-runtime-localized-keys#

Retain every key that a localized string key built at runtime without a literal prefix may look up.

Key retain_runtime_localized_keys · flag, --no-retain-runtime-localized-keys to switch off · default false.

See Analysis: Keys built at runtime.

Retention#

--retain-public#

Retain all public declarations, recommended for framework and library projects.

Key retain_public · flag, --no-retain-public to switch off · default false.

See Getting started: Quick start, Configuration: The configuration file, Analysis: Open and final, Framework conventions and retention: SPI.

--no-retain-spi#

Public SPIs to analyze even when retain_public is enabled.

Key no_retain_spi · list of strings · default empty.

See Framework conventions and retention: SPI.

--retain-assign-only-properties#

Retain properties that are assigned but never read.

Key retain_assign_only_properties · flag, --no-retain-assign-only-properties to switch off · default false.

See Analysis: Assign-only properties.

--retain-assign-only-property-types#

Property types to retain when assigned but never read.

Key retain_assign_only_property_types · list of strings · default empty.

See Analysis: Assign-only properties.

--retain-objc-accessible#

Retain declarations exposed to Objective-C, implicitly (NSObject subclasses) or with @objc / @objcMembers.

Key retain_objc_accessible · flag, --no-retain-objc-accessible to switch off · default false.

See Analysis: Open and final, Framework conventions and retention: Objective-C, Framework conventions and retention: JavaScriptCore, FAQ: Does it analyze Objective-C?.

--retain-objc-annotated#

Retain declarations exposed to Objective-C with @objc / @objcMembers only.

Key retain_objc_annotated · flag, --no-retain-objc-annotated to switch off · default false.

See Framework conventions and retention: Objective-C, FAQ: Does it analyze Objective-C?.

--retain-js-accessible#

Retain protocols that inherit JSExport, their members and the members of conforming types that satisfy them.

Key retain_js_accessible · flag, --no-retain-js-accessible to switch off · default false.

See Framework conventions and retention: JavaScriptCore.

--retain-unused-protocol-func-params#

Retain unused protocol function parameters, even if unused in all conforming functions.

Key retain_unused_protocol_func_params · flag, --no-retain-unused-protocol-func-params to switch off · default false.

See Analysis: Protocol function parameters.

--retain-unused-parameters-without-default#

Retain unused function parameters that have no default value.

Key retain_unused_parameters_without_default · flag, --no-retain-unused-parameters-without-default to switch off · default false.

See Framework conventions and retention: Unused parameters without a default value.

--retain-swift-ui-previews#

Retain SwiftUI previews.

Key retain_swift_ui_previews · flag, --no-retain-swift-ui-previews to switch off · default false.

See Framework conventions and retention: SwiftUI.

--retain-unused-imported-modules#

Names of imported modules to retain even when unused.

Key retain_unused_imported_modules · list of strings · default empty.

See Analysis: Unused imports, Analysis: System framework imports.

--external-encodable-protocols#

External protocols that inherit Encodable; the properties and CodingKey enums of conforming types are retained.

Key external_encodable_protocols · list of strings · default empty.

See Framework conventions and retention: Codable.

--external-codable-protocols#

External protocols that inherit Codable; the properties and CodingKey enums of conforming types are retained.

Key external_codable_protocols · list of strings · default empty.

See Framework conventions and retention: Codable.

--external-test-case-classes#

XCTestCase subclasses that live in external targets.

Key external_test_case_classes · list of strings · default empty.

See Framework conventions and retention: XCTestCase.

--retain-codable-properties#

Retain properties on Codable types (including Encodable and Decodable).

Key retain_codable_properties · flag, --no-retain-codable-properties to switch off · default false.

See Framework conventions and retention: Codable.

--retain-encodable-properties#

Retain properties on Encodable types only.

Key retain_encodable_properties · flag, --no-retain-encodable-properties to switch off · default false.

See Framework conventions and retention: Codable.

--retain-equatable-properties#

Retain properties on Equatable types, including Hashable types.

Key retain_equatable_properties · flag, --no-retain-equatable-properties to switch off · default false.

See Framework conventions and retention: Equatable and Hashable.

--retain-hashable-properties#

Retain properties on Hashable types.

Key retain_hashable_properties · flag, --no-retain-hashable-properties to switch off · default false.

See Framework conventions and retention: Equatable and Hashable.

--retain-synthesized-uses#

Retain stored properties of types whose values are described through reflection (print, dump, String(describing:), interpolation).

Key retain_synthesized_uses · flag, --no-retain-synthesized-uses to switch off · default false.

See Framework conventions and retention: Synthesized uses, Framework conventions and retention: Equatable and Hashable.

--retain-attributes#

Retain declarations that have one of the given attributes (without the @), optionally per declaration kind with '<attribute>:kind1,kind2'.

Key retain_attributes · list of strings · default empty.

See Framework conventions and retention: Retaining by attribute, Comment commands: Other ways to keep code, Configuration: Checking a configuration file.

Output#

--format#

Output format of the results.

Key format · one of xcode, csv, json, checkstyle, codeclimate, github-actions, github-markdown, gitlab-codequality, sarif · default xcode.

See Getting started: How a scan works, Getting started: Results and messages, Configuration: Command line and file, Output formats.

--relative-results#

Report paths relative to the project root, or to relative_results_base.

Key relative_results · flag, --no-relative-results to switch off · default false.

See Getting started: How a scan works, Output formats, Output formats: Paths, Continuous integration: Reusing the build.

--relative-to#

Directory the result paths are relative to when relative_results is in effect.

Key relative_results_base · string · default none.

See Configuration: Paths, Output formats: Paths, Continuous integration: Reusing the build, Continuous integration: GitLab CI.

--write-results#

Also write the formatted results to a file.

Key write_results · string · default none.

See Getting started: Results and messages, Getting started: Exit status, Configuration: Paths, Output formats: Writing to a file.

--skip-stdout-results#

Do not print the results to stdout; requires write_results.

Key skip_stdout_results · flag · default false.

See Getting started: Results and messages, Getting started: Exit status, Output formats: Writing to a file.

--quiet#

Print only the results.

Key quiet · flag, --no-quiet to switch off · default false.

See Getting started: Results and messages, Output formats: Writing to a file, Continuous integration: Reusing the build, Continuous integration: Quiet reports.

--verbose#

Enable verbose logging.

Key verbose · flag, --no-verbose to switch off · default false.

See Getting started: Results and messages, Configuration: Writing the file from a scan, Analysis: Keys built at runtime, Analysis: Metal functions.

--color#

Colored output mode. --no-color is a hidden alias of --color never.

Key color · one of auto, always, never · default auto.

See Output formats: xcode.

--strict#

Exit with status 1 if any result is reported.

Key strict · flag, --no-strict to switch off · default false.

See Getting started: How a scan works, Getting started: Exit status, Continuous integration: Reusing the build, Continuous integration: Quiet reports.

--disable-update-check#

Do not check for a new version.

Key disable_update_check · flag, --no-disable-update-check to switch off · default false.

See Continuous integration: Reusing the build, FAQ: Does it send data anywhere?.

Baselines#

--baseline#

Baseline file whose entries are hidden from the results.

Key baseline · string · default none.

See Getting started: How a scan works, Configuration: Paths, Baselines: Options, Baselines: Baseline ratchet.

--write-baseline#

Write the results to a baseline file, keeping the entries of baseline.

Key write_baseline · string · default none.

See Getting started: How a scan works, Configuration: Paths, Baselines: Options, Baselines: File format.

--prune-baseline#

Rewrite the baseline file keeping only the entries that still match a result; requires baseline.

Key prune_baseline · flag, --no-prune-baseline to switch off · default false.

See Baselines: Options, Baselines: File format, Baselines: Baseline ratchet, Continuous integration: Baseline ratchet.

--strict-baseline#

Exit with status 1 if the baseline holds entries that no longer match; requires baseline.

Key strict_baseline · flag, --no-strict-baseline to switch off · default false.

See Getting started: Exit status, Baselines: Options, Baselines: Baseline ratchet, Roadmap: Published.

Other commands#

outskirts check-update, outskirts clear-cache, outskirts config check, outskirts config schema and outskirts version: see Commands.