About FSMonitor

FSMonitor is a macOS application that can monitor and report all modifications to your file system as they are happening.

Tracked changes include:

• file creation
• deletion
• change of content
• renames
• change of attributes (i.e. modifications to permissions or owner)

Basic Operation

To start recording the file system event, launch the FSMonitor application and click the button in the toolbar. To pause monitoring events, click the button. You can also use the Space key to start and pause recording.

You can start and pause the FSMonitor multiple times.

You can save FSMonitor recordings (with ⌘S) and reopen the saved documents later. You can create, save, and open as many documents as you want.

Examining the changes

FSMonitor categorizes all file system changes into the following five categories. You will see them referenced in different places in the app. The categories are:

• 🆕 File has been newly created.
• ↗️ ↘️ The file moved from (or moved to) another location.
• ✏️ The content of the file has been modified.
• 🛠 The metadata of the file has been modified (for example it changed its owner or permissions).
• ❌ The file has been deleted.

Main View Modes

FSMonitor provides four different ways to display the changes that occurred. You can choose between the view modes with the following control in the toolbar:

To switch to another view, click on the segment that corresponds to the view you want to switch to. The segments represent the tree view, list view, column view, and text view respectively. The actions are also available from the "View" menu, or you can use the corresponding shortcuts ⌘1, ⌘2, ⌘3, ⌘4.

It is worth pointing out that in all view modes you can:

• copy or drag file paths into other applications or into a filter text field.
• reveal files in the Finder, Terminal, or in a "Quick Look" window.
• filter the displayed events so you only see the changes you are interested in.
• select a file and examine detailed information about it in the inspector

The Tree View

The tree view gives you a custom hierarchical overview over the changed files.

The file icons have a little badge at the top right that indicates how many events have been recorded for that particular file path. If it has the red "strike through" overlay, it means that the last known event for that file did either delete or move it. Note that this doesn't necessarily mean that the file is currently not present. For example it could have been recreated after the recording of events stopped.

Hiding files

If you are not interested in changes happening in a certain directory, you can hide events for it. Simply select a file and press the ⌫ (Delete) key. This will hide all children of the directory, and the file will be displayed with a distinctive gray look:

To reveal hidden children again, press ⌘⌫ (Cmd-Delete).

These actions are also available from the "View" menu, and from the contextual menu.

You can open files in other applications as described in the section Opening files in other Applications.

The List View

The list view displays all file system events in a list. By default the newest events are at the bottom, but you can adjust the sort order by clicking on the column headers. This view uses the least system resources, so it is a good choice if you have a lot of changes that might slow down the app. The list has the following columns:

• "Kind": The category of the change.
• "PID": The pid ("process identifier") of the process that made the file system change.
• "Name": The name of the process that made the file system change (if available).
• "Path": The path of the changed file.
• "Date": The date of when the files system change occurred.

You can open files in other applications as described Opening files in other Applications.

The Column View

This view displays the changed paths in a column view, similar to the one that is also available in the Finder. It is useful when you exactly know which directory you want to watch.

As in the tree view, the file icons have a little badge at the top right that shows how many events have been recorded for that particular file. If it has the red "strike through" overlay, it means that the last known event for that file did either delete or move it. Note that this doesn't necessarily mean that the file is currently not present. For example it could have been recreated after the recording of events stopped.

You can open files in other applications as described in the section Opening files in other Applications.

The Text View

The text view displays the file system events in a list similar to the list view, but in the plain text format. This means that many actions from the very powerful native macOS text editing system are available, most prominently the search functionality. Press ⌘F (Cmd-F) to start searching:

You can open files in other applications as described in the section Opening files in other Applications.

Clearing the displayed Events

Sometimes you may want to start over with a clean window after you already started recording. To do that you can click the button in the toolbar. The same action is also available from "Clear" menu item in the "View" menu, or you can use the ⌘K (Cmd-K) shortcut.

The recorded events that are hidden like that are not deleted, and you can display them again by clicking and holding the button and then choosing "Reload":

You can also use the "Reload" menu item in the "View" menu, or simply use the ⌥⌘K (Opt-Cmd-K) shortcut.

Filtering

You can filter which events are being displayed using a filter:

To start filtering, click the button in the toolbar. You can also use the "Filter" menu item in the "Edit" menu, or use the shortcut ⌥⌘F (Opt-Cmd-F). The same shortcut can be used to hide the filter again.

You can filter for

• the path of the changed file
• the event category
• the PID (process identifier) of the process that caused the event
• the name of the process that caused the event
• the path of the process that caused the event

It is possible to create filters with complex nested rules. To create a nested rule, hold the ⌥ (Option) key and click the button with the three little dots:

You can save filters so that you can reuse them. To save a filter click and hold the button and choose Save Filter...:

You can also use the "Filter" menu item in the "Edit" menu to save a filter.

Saved filters can be loaded by clicking and holding the button and clicking on the name of the filter you want to load:

The saved filters are also available from the "Filter" menu item in the "Edit" menu.

To delete a saved filter, click and hold the button to show the filter menu, then press the ⌥ (Option) key, and click on the name of the filter you want to delete:

When the checkbox "Discard non-matching events" is selected, all events that do not match the current filter get discarded permanently while recording. This can help to improve performance. With a narrow enough filter, it is now realistic to have FSMonitor running for longer periods of time. To warn you that FSMonitor is discarding events, the filter icon in the toolbar will show ⚡︎ symbol when a filter with this option is active.

Opening files in other Applications

FSMonitor can open the files it displays in the Finder, the Terminal, or in a Quick Look preview.

You can double click on a file to reveal it in the Finder (except in the text view, where you can ⌘-click).

More options are available from the "File" menu, with the following shortcuts:

• "Reveal in Finder": Press ⏎ (Enter) to reveal the selected file in the Finder
• "Quick Look": Press ⌘⏎ (Cmd-Enter) to reveal the selected file in the Quick Look preview.
• "Reveal in Terminal": Press ⇧⌘⏎ (Shift-Cmd-Enter) to reveal the selected file in the Terminal. The selected file's parent directory (or the file itself if it is a directory) will be the working directory of the opened Terminal window.

The same options are also available from the contextual menu for displayed files. Right-click (or ctrl-click) on a file to bring up the contextual menu.

The Inspector

To toggle the inspector, click the button in the toolbar. You can also use the "Show Info" menu item in the "View" menu, or use the ⌘I (Cmd-I) shortcut.

Use the inspector to examine the details of the selected event. It displays all information FSMonitor was able to collect about it.

It is divided into several sections:

Event Switcher

This is only visible when using the tree or column view, if the selected file has multiple events associated with it. Click on the arrows to switch between the events.

Status Section

The status section displays information about the current status of the file. Thus the information displayed is similar to what you would see in a Finder "Get Info" window.

You can click on the little arrow icon after the path to reveal the file in the Finder.

If the file is not present anymore, only the path can be displayed.

Event Section

The event section provides all the information FSMonitor know about the event itself. It has the following fields (not all of these are displayed all the time):

• Category: The broad category of the event.
• Event Type: The detailed description of the event kind.
• Date: The date the event occurred.
• UID: The UNIX user id and user name the file had after this event.
• GID: The UNIX group id and group name the file had after this event.
• Mode: The UNIX permissions the file had after this event.
• Inode: The inode number this file had after the event. The inode is unique identifier a file has in your file system. It normally is not relevant, but for example is also displayed by the stat Terminal command.
• Device: The file system number of the device (e.g., the disk partition) this file did reside on. It is similar to the inode and is also displayed by the stat command.
• Source: If the event category is of kind "Moved To", this displays the path to where the file came from. Click on the small arrow to reveal this location in the Finder.
• Destination: If the event category is of kind "Moved From", this displays the path where the file moved to. Click on the small arrow to reveal this location in the Finder.

Process Section

The process section displays the information FSMonitor has about the process that caused the event. Note that in some situations only the PID will be know, for example if the process exited before FSMonitor could gather information about it.

The section has the following fields (not all of these are displayed all the time):

• PID: The process id and process name of the process that caused the event.
• PPID: The parent process id and parent process name of the process that caused the event.
• Path: The path to the process. Click the small arrow button to reveal it in the Finder.
• UID: The user id and and user name under which the process was running.
• GID: The group id and and group name under which the process was running.

Session Section

This section display information about the "session" under which this process was recorded. Every time you start recording, FSMonitor starts a new session. This can be useful since an FSMonitor document in theory could contain events recorded on different computers. The session information can help you to identify the host computer.

The section has the following fields:

• Host Name: The host name of the computer this event was recorded on.
• Host Serial: The host serial number of the computer this event was recorded on.
• Host MAC: The MAC address of the computer this event was recorded on.
• Session ID: A random identifier FSMonitor assigned to this session.

Exporting

FSMonitor can export recorded events in formats that make it easy to analyze them with other tools. To export, use the "Export..." menu item in the "File" menu.

There are currently two formats available:

• JSON
• Plain text

When you select the plain text format, you can specify if it should use emoji to identify the event categories. If this option is not specified, the categories will have plain text descriptions.