Find
Free & PremiumThe Find window (Find in files) finds text in many files at once and replaces it if you want. It searches while you type, groups the hits by folder and file, and shows a preview with the match on the right. Files whose name matches the search are listed too, a new, still empty file for example.
What you do here
- Where to search: project, folder, open files, git changes, your own scopes, file mask
- Replace: in one file or across all hits, with undo
- On a server: search in a folder of a connection (Premium)
How to search
- Press ⇧⌘F (or Edit ▸ Find in files). By default a floating window opens over the code area.
- Type the search term. The hits appear after a short pause, grouped by folder, file and line. A status line above the list names hits, files and duration, plus the number of matching file names.
- Pick a hit with ↑ ↓ (with ⌥ from file to file). The preview on the right shows the spot in the file.
- ↩ opens the hit in the editor, ⌘↩ in a split next to it. Esc closes the window.
Page layout
Search field with these switches:
| Switch | Effect |
|---|---|
| Match case | matches exactly this spelling only |
| Whole word | does not match the term as part of a longer word |
| Regular expression | search with regex. An invalid expression is searched as text; the status line says so. |
| Multiline | regex: . also matches line breaks; text: \n stands for a line break |
| Fuzzy | allows one typo per word of five or more characters |
| Add filter | puts a filter as a chip into the search field, see below |
| History (⌃↓) | the last 50 searches with their options |
| Favorites | Save as favorite … keeps the current search under a name |
| Replace (⇧⌘R) | shows the replace field, see Replace |
Scope row below it: Project, Folder, Open files and More, the Ignored folders box and the File mask, see Where to search.
Hit list on the left, preview on the right. In the preview Show the whole file shows the whole file instead of the hit regions only; Open in split and Open open it.
Filters in the search field
Type them directly or use Add filter:
| Filter | Meaning |
|---|---|
ext:php |
File extension |
path:src |
Path contains |
-path:vendor |
Exclude path |
size:<1mb |
Smaller than 1 MB |
changed:7d |
Changed in the last 7 days |
git:modified, git:staged |
Git-changed files only, Staged files only |
foo AND bar |
both terms in the same file, up to eight terms |
"…" |
Exact phrase |
A filter becomes a chip. Double-click edits it, ⌫ at the start of the field removes the last one.
After the search
Below the search field, buttons narrow the result further without searching again: per file extension (Only .php …), Project code only (without vendor and node_modules), and … hidden · show when you have hidden files or folders. You hide them with a right-click on a hit (Hide file, Hide folder …). Group by folder and Flat list switch the display.
Pin the result
Pin result as a tab turns the hit list into a tab. There you tick hits off as done with Space, see the progress (“3 of 12 done”), hide finished ones and search again with Search again. That helps with clean-up work across many files.
Floating or docked
In the floating window, Dock as tool window docks the search into the bottom dock. Docked, Float as a window makes it float again. ⇧⌘F then always opens the search the way you had it last.
Free and Premium
Searching on your Mac is free. Searching in a folder on a server is Premium.
The settings are under Settings › Search, see Search: default excludes, .gitignore, hidden files, size and hit limits, live search, grouping and history.
Where to search Free
The row below the search field decides which files the search goes through: the whole project, one folder, the open files, git changes only, a folder anywhere on the Mac or a scope of your own that you saved. The file mask narrows it to file types, and the Ignored folders box adds folders such as vendor that are otherwise left out.
Where to find it
Open the search with ⇧⌘F. The scope row sits right under the search field. From the project tree, right-click a folder ▸ Find in folder … to land in that folder's scope directly.
The scopes
| Scope | What is searched |
|---|---|
| Project | the project folder and every attached folder |
| Folder | a folder of your choice. A click opens the Finder dialog; afterwards the button reads Folder: name. With Find in folder … in the project tree the folder is set already. |
| Open files | the files open as tabs. Greyed out when none is open. |
Under More you find:
- Attached folders: only the attached folders, without the main project
- Git: changed files and Git: staged files
- Folder on the Mac: any folder, outside the project too. Choose a folder on the Mac … picks another one.
- servers, with Premium:
server:/pathwith the connection's name, see On a server - your own scopes
- Save scope … and Delete scope ▸
Scopes that are not available right now (with no attached folders, for example) are greyed out. The editor remembers the chosen scope per project.
How to do it
Save a scope of your own
- More ▸ Save scope …
- Enter a Name, for example “Storefront templates”.
- Enter the Patterns relative to the project, several separated by spaces, for example
custom/plugins/*/src/Resources/views/** !**/admin/**.!patternexcludes. - The scope then sits under More and applies to this project. Delete scope ▸ removes it again.
Narrow down with the file mask
The File mask on the right of the scope row filters by file names:
*.css, *.phpsearches these files only. A comma separates patterns.test.cssfinds that file in any folder.!*.min.jsexcludes.src/**/*.tsfilters by path.
The box in front of the field turns the mask on and off; it is kept either way. The arrow in the field shows suggestions: Recently used, In the project (the most common extensions) and In the hits. If a search with a mask finds nothing, the status line offers to search without file mask.
What stays out
By default the search leaves out:
- the Default excludes:
node_modules,vendor,var/cache,.idea,*.min.js,*.min.css,*.map - whatever
.gitignoreexcludes (Respect .gitignore) - binary files and files over 5 MB
The Ignored folders box adds node_modules, vendor, .git, build folders (dist, build …) and everything in .gitignore for this search. You set the defaults under Settings › Search (Search). Hidden files such as .env and .htaccess are searched by default.
File names too
The search also lists files whose name contains every search term, even if nothing in their content matches: empty, binary and large files included. They carry the hint File name, and the status line counts them (File names: …). Scope, file mask, excludes and .gitignore apply here too, with 1,000 files per search at most. This does not exist on a server.
The search finds accented letters in both Unicode forms. A typed “ü” also matches text that macOS stored decomposed, for example in copied file names.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
Hits in vendor are missing |
default exclude | tick Ignored folders |
| This scope is not available right now | There are no open files or no attached folders, for example. | pick another scope |
| The folder no longer exists | The chosen folder was deleted or moved. | pick Folder again |
| Invalid file pattern | The mask holds a pattern that does not work. | fix the mask |
See also
Replace Free
The search window replaces hits in one file or in all files of the scope. Before replacing you see every occurrence, untick single ones and can undo everything with one click. Every old state goes into the local history first.
Where to find it
- ⇧⌘R (Edit ▸ Replace in files) opens the search with the replace field.
- In the open search window, the Replace (⇧⌘R) switch.
How to do it
- Press ⇧⌘R and enter the search term at the top.
- Enter the new text in the field Replace with …. With Regular expression you insert groups with
$1,$2. - Check the hits. The list and the preview show what each spot will read. The box Replace this occurrence on hits, files and folders takes single occurrences out or back in.
- Replace:
- In this file: only in the previewed file.
- Replace all (⌘↩ in the field): every checked occurrence.
- Afterwards the status line says how many occurrences in how many files were replaced. Undo next to it brings every old state back.
Options
| Option | Meaning |
|---|---|
| Preserve case | matches the case at each spot: foo becomes bar, Foo becomes Bar, FOO becomes BAR |
| Regular expression | $1 and so on for groups |
| Match case, Whole word | apply when replacing too |
What happens in the background
- From a number of files you can set, the editor asks first “Replace in … files?” and names the number of occurrences. By default from 50 files (Settings › Search › Ask before replacing from).
- Before writing, the editor keeps each file's old state in the local history. Undo resets everything. Files you edited since are left as they are.
- Skipped are files larger than 2 MB, read-only or binary files, files with an unclear encoding, files with unsaved changes in the editor and files that changed since the search. The status line gives the number, the tooltip the files and reasons.
Where replacing does not work
Replace works with a single search term in local scopes only. There is no replace on a server. If the scope is a server, the window says so below the field.
Troubleshooting
| What you see | What to do |
|---|---|
| … files skipped | read the tooltip. Save unsaved files, then search and replace again. |
| changed meanwhile, please search again | search again, then replace |
| characters do not fit the encoding | The new text cannot be stored in the file's encoding, such as emoji in Latin-1. Switch the file to UTF-8. |
See also
On a server Premium
With Premium the search window also searches a folder on a server, through a connection from the Remote window. The search runs on the server itself, with rg or grep. The files are not downloaded for it. Before a search starts, the editor checks the server's load so that a search does not slow down a running website.
Where to find it
- In the server tree: right-click a folder ▸ Find in folder …. The search window opens with this folder as scope.
- In the search window under More: every server you are connected to, or have already searched in this project, as
server:/pathwith the connection's name. - In the search field: type
server:/var/www/shop(with a space at the end). It becomes the scope of that folder on the server that is currently open.~stands for the home folder.
How to do it
- Right-click the folder in the server tree ▸ Find in folder ….
- Type the search term.
- Press ↩. On a server the editor never searches while you type.
- The hits appear as in a local search. ↩ opens a hit as a server file with a working copy (see Files on the server).
The editor remembers the folder per server for this project.
Load and limits
- Before every search the editor checks the server's load. If it is above your limit, it asks The server is busy and names the load and the number of cores.
- If you pick
/or a folder with a very large tree (such as a host's home folder), it asks Search the whole of …? and recommends a project folder. - Search anyway allows exactly that for one minute.
- Only one search at a time runs on a server.
- At the hit limit the search stops and ends the process on the server.
- Replace, Fuzzy and Multiline do not exist on a server; the switches are greyed out. File names as hits do not exist there either.
Settings
Under Settings › Remote, group Search on the server (Remote):
| Setting | Meaning | Default |
|---|---|---|
| Leave out on the server | folders and patterns a server search never walks. A name means any folder of that name, a path like var/cache that folder at any depth. |
.git, node_modules, vendor, var/cache, var/log, public/media, public/thumbnail, files |
| Ask when the load is above | Above this value times the number of cores, the editor asks first. | 0.8 |
| Hit limit | at most this many hits, 2000 at most | 2000 |
The Ignored folders box in the search window adds vendor and node_modules back on the server too.
File names on a server you find with Search everywhere (⇧⇧) in the Servers tab.
Free and Premium
Searching on a server is Premium.
Troubleshooting
| What you see | What to do |
|---|---|
| Server busy (not searched) | search later or Search anyway |
| A search is already running on this server | wait until it is done |
| This folder does not exist on the server | check the folder, pick it again in the server tree |
| Server paths start with / or ~ | fix the path after server: |
| The server did not answer the check before the search | check the connection, reconnect |
| This mode does not work on a server | turn off Fuzzy and Multiline |