A fast and efficient command-line tool for comparing and synchronizing directories, and for splitting album images into tracks with cue sheets.
- Recursive directory comparison - Scan subdirectories automatically
- Multiple output formats - Text, JSON, or summary output
- Fast concurrent processing - Uses Swift's modern concurrency for optimal performance
- Smart file comparison - Quickly identifies identical, modified, and unique files
- Fuzzy filename matching - Match files with similar names using configurable precision threshold
- Fuzzy size tolerance - Treat fuzzy-matched files with similar sizes as renamed rather than modified
- Clear exit codes - Easy integration with scripts and CI/CD pipelines
- Pattern-based file filtering - Use .filesignore to exclude files from operations
- Configuration files - Use .files to set default options per directory
- One-way sync - Mirror source directory to destination
- Two-way sync - Bidirectional synchronization with conflict resolution
- Conflict resolution strategies - Keep newest, source, destination, or skip
- Dry-run mode - Preview changes before applying them
- Safe operations - Creates intermediate directories and validates paths
- Lossless, bit-exact cuts - Tracks keep the source format and bit depth
- FLAC, WAV, AIFF natively through Core Audio; APE and WavPack through ffmpeg
- Tags from the cue sheet - FLAC tracks get title, artist, album, track and disc numbers
- Legacy encodings - Detects Windows-1251, Windows-1252, Shift JIS and others
- Program Status Protocol (OSC 7501) - Terminals that support it can show progress on the tab and notify when a long sync, copy or cut finishes
Files requires macOS 26 or later.
The latest macOS build can be downloaded from the GitHub Releases page.
See the Building section below for instructions on building from source.
Files supports .filesignore files to exclude certain files and directories from comparison and sync operations. This works similarly to .gitignore.
The tool automatically looks for .filesignore files in three locations (in order):
- User home directory:
~/.filesignore- Global patterns for all operations - Source/left directory:
<source-dir>/.filesignore - Destination/right directory:
<dest-dir>/.filesignore
Patterns from all found files are merged together.
*- Matches any characters except/?- Matches a single character except/**- Matches zero or more directories/at start - Pattern is relative to directory root/at end - Pattern matches directories only (e.g.node_modules/ignores everything inside anynode_modulesfolder)!- Negates a pattern (includes files that were previously excluded). As in.gitignore, it can't re-include a file inside an ignored directory#- Comment line- Empty lines are ignored
By default, .filesignore and .files are always ignored and will not be copied during sync operations. This prevents configuration files from being propagated to destination directories.
To explicitly include them in sync operations, add negation patterns:
!.filesignore
!.files
# Ignore build artifacts
*.o
*.class
build/
# Ignore dependencies
node_modules/
vendor/
# Ignore version control
.git/
.svn/
# Ignore OS files
.DS_Store
Thumbs.db
# Ignore all log files
*.log
# But keep important.log
!important.log
# Ignore config.json only at root
/config.json
# Ignore all .txt files in build directory and subdirectories
build/**/*.txt
You can disable .filesignore pattern matching with the --no-ignore flag:
files compare dir1 dir2 --no-ignore
files sync source dest --no-ignoreInstead of passing options via CLI flags every time, you can create a .files configuration file in either the left or right directory. This is especially useful for directories that always need the same settings.
The tool looks for .files in two locations:
- Source/left directory:
<source-dir>/.files - Destination/right directory:
<dest-dir>/.files
Right directory values override left directory values. CLI flags override all .files settings: every on/off flag has a --no- form (for example --no-dry-run, --no-deletions, --no-verbose, and --ignore to undo noIgnore), so you can switch off a value a .files turned on.
For sync and cp, the settings that can delete or overwrite files are read only from the destination .files or from CLI flags:
deletionstwoWayconflictResolutionnoIgnore
If the source .files contains any of them, they are ignored and a warning naming the file is printed to stderr. This keeps a .files inside a folder you sync from (a download, a USB drive, a shared folder) from deleting or overwriting files in your destination. compare changes no files, so it reads every setting from both directories.
Simple key = value format, one per line. Comments start with #:
# Fuzzy matching settings
matchPrecision = 0.8
sizeTolerance = 0.2
# Sync behavior
recursive = true
deletions = false
| Key | Type | Description |
|---|---|---|
matchPrecision |
0.0–1.0 |
Fuzzy filename matching threshold |
sizeTolerance |
0.0–1.0 |
File size difference tolerance for fuzzy matches |
concurrentReads |
1 or more |
How many files to read and compare at once (default: 4) |
recursive |
true/false |
Scan subdirectories recursively |
deletions |
true/false |
Delete files not in source (one-way sync) |
showMoreRight |
true/false |
Show additional right-side diff info |
dryRun |
true/false |
Preview changes without applying |
verbose |
true/false |
Show detailed output |
format |
text/json/summary |
Output format |
twoWay |
true/false |
Enable two-way sync |
conflictResolution |
newest/left/right/skip |
Conflict resolution strategy |
noIgnore |
true/false |
Disable .filesignore loading |
Boolean values accept: true/false, yes/no, 1/0.
See .files.example for a complete example with documentation.
You can disable .files configuration loading with the --no-config flag:
files compare dir1 dir2 --no-config
files sync source dest --no-configLike .filesignore, the .files configuration file is automatically excluded from comparison and sync operations. It will not be copied to destination directories.
Files tells the terminal what it is doing with the Program Status Protocol (OSC 7501), so a terminal that supports it can show progress and notify you when a command finishes. Terminals that don't support the protocol ignore the reports.
| Command | While it runs | When it ends |
|---|---|---|
compare, compare-snapshot |
Comparing left and right |
Done, with the number of differences, or error |
sync, cp |
The route, then each file being copied, updated or deleted | Done, with the number of operations, or error if any failed |
cut |
The album, with the share of tracks cut so far | Done, or error if any track failed |
Reports go to the controlling terminal, never into redirected output, so pipes and --format json stay clean. Set FILES_STATUS to change that:
FILES_STATUS=off files sync src dst # send no reports
FILES_STATUS=status.log files cut album.cue # append the reports to a fileFiles has three main commands: compare (default), sync, and cp.
Compare two directories and report differences:
files compare <left-directory> <right-directory> [options]
# or simply (compare is the default command):
files <left-directory> <right-directory> [options]--recursive/--no-recursive- Scan subdirectories recursively (default: recursive)--match-precision THRESHOLD- Fuzzy filename matching threshold from 0.0 to 1.0 (default: 1.0 for exact matching). Lower values enable matching files with similar names using Levenshtein distance--size-tolerance TOLERANCE- File size difference tolerance for fuzzy matches from 0.0 to 1.0 (default: 0.0 for exact comparison)--concurrent-reads N- How many files to read and compare at once, at least 1 (default: 4). Raise it for network volumes; see Comparing on network volumes--verbose,-v- Show detailed output with all file paths--format FORMAT- Output format:text(default),json,summary--no-ignore- Disable .filesignore pattern matching--no-config- Disable .files configuration loading--help,-h- Show help message--version- Show version information
0- Directories are identical1- Differences found2- Error occurred (invalid directory, access denied, etc.)
Copy new and modified files from source to destination (without deletions):
files cp <source-directory> <destination-directory> [options]This is a convenience command equivalent to files sync --no-deletions with one-way mode. It's useful for updating a destination directory with new and changed files from source while preserving any extra files in the destination.
--show-more-right- Scan leaf directories on the right side for additional diff information--match-precision THRESHOLD- Fuzzy filename matching threshold from 0.0 to 1.0 (default: 1.0 for exact matching)--size-tolerance TOLERANCE- File size difference tolerance for fuzzy matches from 0.0 to 1.0 (default: 0.0 for exact comparison)--concurrent-reads N- How many files to read and compare at once, at least 1 (default: 4). Raise it for network volumes; see Comparing on network volumes--dry-run- Preview changes without applying them--verbose,-v- Show detailed output with all operations--format FORMAT- Output format:text(default),json,summary--no-ignore- Disable .filesignore pattern matching--no-config- Disable .files configuration loading
# Preview what would be copied
files cp /source /backup --dry-run --verbose
# Copy new and modified files
files cp /source /backup --verboseSynchronize two directories:
files sync <source-directory> <destination-directory> [options]--two-way/--no-two-way- Enable bidirectional sync (default: one-way)--conflict-resolution STRATEGY- For two-way sync:newest(default),source,destination,skip--recursive/--no-recursive- Scan subdirectories recursively (default: recursive)--deletions/--no-deletions- Delete files in destination that don't exist in source (one-way sync only, default: false)--show-more-right- Scan leaf directories on the right side for additional diff information (one-way sync without deletions only)--match-precision THRESHOLD- Fuzzy filename matching threshold from 0.0 to 1.0 (default: 1.0 for exact matching). Lower values enable matching files with similar names using Levenshtein distance--size-tolerance TOLERANCE- File size difference tolerance for fuzzy matches from 0.0 to 1.0 (default: 0.0 for exact comparison)--concurrent-reads N- How many files to read and compare at once, at least 1 (default: 4). Raise it for network volumes; see Comparing on network volumes--dry-run- Preview changes without applying them--verbose,-v- Show detailed output with all operations--format FORMAT- Output format:text(default),json,summary--no-ignore- Disable .filesignore pattern matching--no-config- Disable .files configuration loading
One-way sync (default): Copies and updates files from source to destination
- Copies files that exist only in source
- Updates files that differ between source and destination
- By default, does NOT delete files that exist only in destination
- Use
--deletionsflag to delete extra files in destination (mirrors source exactly)
Two-way sync (--two-way): Bidirectional synchronization
- Copies files that exist only in either directory to the other
- Never deletes files (syncs in both directions)
- Resolves conflicts for modified files based on
--conflict-resolutionstrategy
newest- Keep the file with the most recent modification time (default)source- Always prefer the source filedestination- Always prefer the destination fileskip- Skip conflicting files, leave both unchanged
Split an album image into tracks using its cue sheet (macOS only):
files cut <cue-file> [options]- FLAC, WAV and AIFF are cut with Core Audio and keep their format and bit depth (16, 20 or 24-bit).
- APE and WavPack need ffmpeg (
brew install ffmpeg), which is found onPATH,/opt/homebrew/binor/usr/local/bin. They are decoded once and written as FLAC. - FLAC tracks are tagged with
TITLE,ARTIST,ALBUM,ALBUMARTIST,COMPOSER,GENRE,DATE,ISRC,TRACKNUMBER,TRACKTOTAL,DISCNUMBERandDISCTOTALfrom the cue sheet, with 8 KB of padding after the tags so a tag editor can change them later without rewriting the audio. WAV and AIFF tracks are not tagged. - Tracks are named
NN - Title.ext, orNN - Performer - Title.extwhen a track's performer differs from the album's.
How tracks are cut:
- A track runs from its
INDEX 01to the next track'sINDEX 01, so pregaps (INDEX 00) stay at the end of the track before them. - The first track of each file starts at the beginning of the file, so a hidden track or lead-in is kept in track 1.
- With several
FILElines, a track ends with its file. - If the audio named by
FILEis missing, the same name with another audio extension is used (a.wavsheet next to a.flacimage), and a sheet with oneFILEalso matches audio named like the cue sheet.
--output DIR,-o DIR- Directory to write the tracks to (default: the cue sheet's directory)--encoding NAME- Cue sheet text encoding as an IANA name, e.g.windows-1251orshift_jis(default: UTF-8, then detected)--overwrite- Replace track files that already exist (a source file is never replaced)--dry-run- List the tracks without cutting them--verbose,-v- Show the source and time range of each track
0- All tracks were cut1- One or more tracks failed (for example, the file already exists)2- The cue sheet could not be read or its audio was not found
# Preview the track names and ranges
files cut "Album.cue" --dry-run --verbose
# Cut into a separate folder
files cut "Album.cue" -o tracksThe --match-precision option enables fuzzy matching of filenames using Levenshtein distance algorithm. This is useful when comparing directories with files that may have typos, slight variations, or systematic naming differences.
-
Threshold value: A number from 0.0 to 1.0
1.0(default): Only exact filename matches0.8: Allows ~20% character differences (recommended for typo detection)0.5: Allows ~50% character differences (very permissive)0.0: Matches any files (not recommended)
-
Matching is based on filename only, not the full path
-
Exact matches are always preferred over fuzzy matches
-
One-to-one mapping: Each right file can only match one left file
-
Best pairs first: the most similar pairs are matched first; ties go to files in the same folder, then to the alphabetically first path, so every run gives the same result
-
Ignore patterns and
--no-recursiveapply to the files considered for matching -
Two-way sync resolves a matched pair between its two actual files and overwrites the losing file in place, so each side keeps its own name
When fuzzy matching is enabled, matched files with different names will almost always have different content. The --size-tolerance option controls how to handle these pairs:
0.0(default): Exact content comparison — files are compared byte-by-byte0.2: Files with sizes within 20% of each other are treated as the same file (renamed)0.5: Files with sizes within 50% are treated as the same file
Formula: files match if abs(size1 - size2) <= min(size1, size2) * tolerance
This is useful for detecting renamed files without treating them as modified.
- Typo detection: Find files with misspelled names (e.g., "report.txt" vs "reprot.txt")
- Version variations: Match files with version numbers (e.g., "file_v1.txt" vs "file_v2.txt")
- Renamed files: Identify files that were slightly renamed between directories
- Import cleanup: Find near-duplicate files from different sources
# Compare with fuzzy matching (80% similarity threshold)
files /backup /current --match-precision 0.8 --verboseOutput shows fuzzy-matched files as "modified":
Modified (2):
~ report.txt (matched with: reprot.txt)
~ document.txt (matched with: documnet.txt)
# Sync files even if names have minor differences
files sync /source /dest --match-precision 0.8 --verboseThis will:
- Match "report.txt" (source) with "reprot.txt" (destination)
- Update the file with correct content
- Create new "report.txt" in destination
# Match similar filenames and treat similar-sized files as renamed
files compare /dir1 /dir2 --match-precision 0.8 --size-tolerance 0.2This matches files with 80% filename similarity. Fuzzy-matched pairs with sizes within 20% of each other are treated as the same file (renamed), not as modified.
# Use higher threshold (90%) for stricter matching
files /dir1 /dir2 --match-precision 0.9Only files with very similar names will match (e.g., "file1.txt" and "file2.txt" won't match, but "report.txt" and "reprot.txt" will).
Comparing reads every file that exists on both sides, a few at a time: 4 by default. That suits a local SSD, where opening files contends in the kernel and reading more at once only uses more CPU. On a network volume each read waits on the server instead, so reading more files at once can be much faster:
files sync ~/Photos /Volumes/NAS/Photos --concurrent-reads 16To use it every time, put it in the .files of the folder on that volume:
concurrentReads = 16
files /path/to/dir1 /path/to/dir2Output:
✗ Directories differ
Only in LEFT (3):
Use --verbose to see file list
Only in RIGHT (2):
Use --verbose to see file list
Modified (1):
Use --verbose to see file list
Summary: 3 left-only, 2 right-only, 1 modified, 10 unchanged
files /path/to/dir1 /path/to/dir2 --verboseOutput:
✗ Directories differ
Only in LEFT (3):
- old-file.txt
- deprecated/config.json
- temp/data.csv
Only in RIGHT (2):
+ new-feature.swift
+ assets/logo.png
Modified (1):
~ config.yaml
Summary: 3 left-only, 2 right-only, 1 modified, 10 unchanged
files /path/to/dir1 /path/to/dir2 --format jsonStatus lines such as Using config: and DRY RUN go to stderr, so stdout holds only the JSON. matches maps each fuzzy-matched left file to the right file it was paired with (empty without --match-precision).
Output:
{
"onlyInLeft": [
"old-file.txt",
"deprecated/config.json"
],
"onlyInRight": [
"new-feature.swift"
],
"modified": [
"config.yaml"
],
"common": [
"README.md",
"main.swift"
],
"matches": {},
"summary": {
"onlyInLeftCount": 2,
"onlyInRightCount": 1,
"modifiedCount": 1,
"commonCount": 2,
"identical": false
}
}files /path/to/dir1 /path/to/dir2 --format summaryOutput:
Identical: no
Only in left: 3
Only in right: 2
Modified: 1
Unchanged: 10
Total files: 16
Compare only top-level files without scanning subdirectories:
files /path/to/dir1 /path/to/dir2 --no-recursive#!/bin/bash
if files /backup /current --format summary; then
echo "Backup is up to date"
else
echo "Backup needs updating"
fiCopy and update files from source to destination (extra files in destination are kept):
files sync /source/dir /backup/dir --dry-run --verboseOutput:
🔍 DRY RUN - No changes will be made
Would perform 4 operation(s)
Copy (3):
would copy new-file.txt
would copy docs/guide.md
would copy src/main.swift
Update (1):
would update config.yaml
Execute the sync:
files sync /source/dir /backup/dir --verboseOutput:
Performed 4 operation(s)
Copy (3):
copied new-file.txt
copied docs/guide.md
copied src/main.swift
Update (1):
updated config.yaml
Summary: 4 succeeded, 0 failed, 0 skipped
Mirror source to destination exactly (deletes extra files in destination):
files sync /source/dir /backup/dir --deletions --dry-run --verboseOutput:
🔍 DRY RUN - No changes will be made
Would perform 5 operation(s)
Copy (3):
would copy new-file.txt
would copy docs/guide.md
would copy src/main.swift
Update (1):
would update config.yaml
Delete (1):
would delete old-file.txt
Execute the sync:
files sync /source/dir /backup/dir --deletions --verboseOutput:
Performed 5 operation(s)
Copy (3):
copied new-file.txt
copied docs/guide.md
copied src/main.swift
Update (1):
updated config.yaml
Delete (1):
deleted old-file.txt
Summary: 5 succeeded, 0 failed, 0 skipped
Synchronize two directories bidirectionally, keeping the newest version of conflicting files:
files sync /dir1 /dir2 --two-way --conflict-resolution newest --verboseOutput:
Performed 4 operation(s)
Copy (3):
copied unique-in-dir1.txt
copied unique-in-dir2.txt
copied another-file.md
Update (1):
updated conflicting-file.txt
Summary: 4 succeeded, 0 failed, 0 skipped
Always prefer the source directory for conflicts:
files sync /source /dest --two-way --conflict-resolution sourceSync unique files but skip conflicting files:
files sync /dir1 /dir2 --two-way --conflict-resolution skip --verbosefiles sync /source /dest --dry-run --format jsonOutput:
{
"operations": [
{
"type": "copy",
"path": "new-file.txt",
"source": "/source/new-file.txt",
"destination": "/dest/new-file.txt"
},
{
"type": "update",
"path": "modified.txt",
"source": "/source/modified.txt",
"destination": "/dest/modified.txt"
}
],
"summary": {
"total": 2,
"succeeded": 0,
"failed": 0,
"skipped": 2
}
}#!/bin/bash
# Mirror production to backup with exact mirroring (including deletions)
echo "Checking what would change..."
files sync /production /backup --deletions --dry-run --format summary
read -p "Proceed with sync? (y/n) " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
files sync /production /backup --deletions --verbose
if [ $? -eq 0 ]; then
echo "Backup completed successfully"
else
echo "Backup failed!"
exit 1
fi
fiKeep two working directories in sync:
# Sync laptop and desktop project directories
files sync ~/projects/myapp /mnt/desktop/projects/myapp --two-way --conflict-resolution newestBuilding needs Swift 6.3 or later (Xcode 26.4 or later).
swift build -c release \
-Xswiftc -O \
-Xswiftc -whole-module-optimization \
-Xswiftc -cross-module-optimization
FilesKit's directory comparison, sync planning, ignore matching and cue pipeline have performance benchmarks in Benchmarks, run from that directory:
swift package --allow-writing-to-package-directory benchmarkYou can copy it to your PATH:
cp .build/release/files /usr/local/bin/Or create a symlink:
ln -s $(pwd)/.build/release/files /usr/local/bin/filesLICENSE: MIT