2.4 KiB
Xcode Search Custom Scopes
What are Xcode Search Scopes?
Xcode's Find navigator supports custom search scopes that let you filter which files are searched. For example, you can limit a search to Swift source files only, or exclude test and localization files to focus on production code.
Custom scopes are stored in xcuserdata/, which is gitignored because it contains per-user Xcode state. This folder provides a shared template and a script to install the scopes into your local workspace without committing user-specific paths.
Setup
Run the setup script from the repo root:
bash Scripts/setup-search-scopes.sh
The script installs the scopes into:
Bitwarden.xcworkspace/xcuserdata/<your-username>.xcuserdatad/IDEFindNavigatorScopes.plist
If a IDEFindNavigatorScopes.plist file already exists (e.g. you have your own custom scopes), the script will prompt you to:
- Overwrite — replace entirely with the shared template
- Merge — append only the template scopes not already present (matched by name)
- Cancel — make no changes
Note: This script is not run automatically by bootstrap.sh. Run it manually whenever the shared scopes are updated.
After running the script, restart Xcode for the new scopes to appear in the Find navigator.
Available Scopes
| Name | Description |
|---|---|
| Not Tests | Excludes files whose names end in Tests.swift. Useful when searching for production code without noise from test files. |
| Not in Localizations | Excludes Localizable.strings and Localizations.swift. Useful when searching for code references without matching localization keys or generated string accessors. |
Using a Scope
- Open the Find navigator (⌘3) and switch to the Find tab.
- Click the scope dropdown (defaults to "In Workspace") next to the search field.
- Select a custom scope from the list.
Adding a New Scope
- In Xcode's Find navigator, click the scope dropdown and choose New Scope…
- Configure the scope's name, predicates, and source in the editor.
- Save the scope — Xcode writes it to your local
IDEFindNavigatorScopes.plist. - Open
Bitwarden.xcworkspace/xcuserdata/<your-username>.xcuserdatad/IDEFindNavigatorScopes.plistand copy the new<dict>entry for your scope. - Paste it into
Xcode/SearchScopes/IDEFindNavigatorScopes.plistin the repo. - Open a PR with the change so teammates can merge it via the setup script.