Dart FileSystemModifyEvent
last modified October 18, 2026
The FileSystemModifyEvent class in Dart represents file system
modification events. It is part of the dart:io library and is
delivered by Directory.watch().
This event is triggered when files or directories are modified in a watched directory. It reports the path of the changed entry and whether its content actually changed.
Basic Definition
FileSystemModifyEvent is a concrete subclass of
FileSystemEvent. It is emitted when the contents or attributes of
an entry in a watched directory change.
Key properties include path, isDirectory,
contentChanged, and type. The
contentChanged flag is true when the file content was
written, and false when only metadata such as timestamps changed.
Basic FileSystemModifyEvent Usage
This example shows how to listen for file system modification events.
import 'dart:async';
import 'dart:io';
void main() async {
var dir = Directory('watch_dir');
await dir.create();
var file = File('${dir.path}/example.txt');
await file.writeAsString('initial content');
late StreamSubscription<FileSystemEvent> subscription;
subscription = dir.watch().listen((event) {
if (event is FileSystemModifyEvent) {
print('Change detected in: ${event.path}');
print('Content changed: ${event.contentChanged}');
subscription.cancel();
}
});
await file.writeAsString('updated content');
await Future.delayed(Duration(seconds: 1));
}
We create the file before starting the watcher, then write to it again. The first
modify event prints the path and the contentChanged flag, after
which the subscription is cancelled.
$ dart main.dart Change detected in: watch_dir/example.txt Content changed: true
Filtering Content Changes
This example demonstrates handling only modifications that changed file content, ignoring attribute-only updates.
import 'dart:async';
import 'dart:io';
void main() async {
var dir = Directory('watch_dir');
await dir.create();
var file = File('${dir.path}/example.txt');
await file.writeAsString('initial content');
late StreamSubscription<FileSystemEvent> subscription;
subscription = dir.watch().listen((event) {
if (event is FileSystemModifyEvent && event.contentChanged) {
print('Content modified: ${event.path}');
subscription.cancel();
}
});
await file.writeAsString('more content');
await Future.delayed(Duration(seconds: 1));
}
The contentChanged flag distinguishes a real content write from a
modification that only touched attributes such as the access or modification
time.
$ dart main.dart Content modified: watch_dir/example.txt
Monitoring Specific Files
This example shows how to watch for changes to a specific file only.
import 'dart:async';
import 'dart:io';
void main() async {
var dir = Directory('watch_dir');
await dir.create();
const targetFile = 'watch_dir/config.json';
var file = File(targetFile);
await file.writeAsString('{}');
late StreamSubscription<FileSystemEvent> subscription;
subscription = dir.watch().listen((event) {
if (event is FileSystemModifyEvent && event.path == targetFile) {
print('Config file changed: ${event.path}');
subscription.cancel();
}
});
await file.writeAsString('{"debug": true}');
await Future.delayed(Duration(seconds: 1));
}
We compare each modify event's path against the target file. This creates a focused watcher that only responds to changes in the specified configuration file.
$ dart main.dart Config file changed: watch_dir/config.json
Handling Multiple Changes
This example demonstrates collecting several changes over a short window.
import 'dart:async';
import 'dart:io';
void main() async {
var dir = Directory('watch_dir');
await dir.create();
var first = File('${dir.path}/first.txt');
var second = File('${dir.path}/second.txt');
await first.writeAsString('one');
await second.writeAsString('two');
var changes = <String>{};
var subscription = dir.watch().listen((event) {
if (event is FileSystemModifyEvent) {
changes.add(event.path);
}
});
await first.writeAsString('one updated');
await Future.delayed(Duration(milliseconds: 200));
await second.writeAsString('two updated');
await Future.delayed(Duration(seconds: 1));
await subscription.cancel();
print('Batch changes detected:');
for (var path in changes) {
print(' $path');
}
}
Dart delivers one event per change; platforms may emit more than one modify event for a single write. Here we collect events over a short window and use a set to de-duplicate them by path before printing the batch.
$ dart main.dart Batch changes detected: watch_dir/first.txt watch_dir/second.txt
Error Handling in File Monitoring
This example adds error handling to file system monitoring.
import 'dart:async';
import 'dart:io';
void main() async {
var dir = Directory('watch_dir');
await dir.create();
var file = File('${dir.path}/example.txt');
await file.writeAsString('initial content');
late StreamSubscription<FileSystemEvent> subscription;
subscription = dir.watch().listen(
(event) {
if (event is FileSystemModifyEvent) {
print('Change: ${event.path}');
subscription.cancel();
}
},
onError: (Object error) {
print('Error: $error');
},
);
await file.writeAsString('updated content');
await Future.delayed(Duration(seconds: 1));
}
The onError callback receives asynchronous watcher failures. The
subscription is cancelled after the first observed change.
$ dart main.dart Change: watch_dir/example.txt
Best Practices
- Specific paths: Filter events to only watch relevant files
- Error handling: Always implement error handlers
- Resource cleanup: Cancel subscriptions when done
- Performance: Avoid heavy processing in event handlers
- Multiple events: De-duplicate by path, since one write may emit several modify events
Source
Dart FileSystemModifyEvent Documentation
This tutorial covered Dart's FileSystemModifyEvent class with practical examples showing basic usage, filtering, monitoring specific files, batching changes, and error handling.
Author
List all Dart tutorials.