Skip to content
velocityzenPublic

About

Files Toolbox

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Files

A fast and efficient command-line tool for comparing and synchronizing directories, and for splitting album images into tracks with cue sheets.

Features

Directory Comparison

  • 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

Directory Synchronization

  • 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

Cue Sheet Splitting

  • 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

Terminal Status

  • 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

Installation

Files requires macOS 26 or later.

Download Pre-built Binary

The latest macOS build can be downloaded from the GitHub Releases page.

Build from Source

See the Building section below for instructions on building from source.

File Filtering with .filesignore

Files supports .filesignore files to exclude certain files and directories from comparison and sync operations. This works similarly to .gitignore.

.filesignore File Locations

The tool automatically looks for .filesignore files in three locations (in order):

  1. User home directory: ~/.filesignore - Global patterns for all operations
  2. Source/left directory: <source-dir>/.filesignore
  3. Destination/right directory: <dest-dir>/.filesignore

Patterns from all found files are merged together.

Pattern Syntax

  • * - 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 any node_modules folder)
  • ! - 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

Default Ignored Files

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

Example .filesignore

# 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

Disabling .filesignore

You can disable .filesignore pattern matching with the --no-ignore flag:

files compare dir1 dir2 --no-ignore
files sync source dest --no-ignore

Configuration with .files

Instead 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.

.files File Locations

The tool looks for .files in two locations:

  1. Source/left directory: <source-dir>/.files
  2. 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.

Settings Read Only from the Destination

For sync and cp, the settings that can delete or overwrite files are read only from the destination .files or from CLI flags:

  • deletions
  • twoWay
  • conflictResolution
  • noIgnore

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.

Format

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

Available Options

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.

Disabling .files

You can disable .files configuration loading with the --no-config flag:

files compare dir1 dir2 --no-config
files sync source dest --no-config

Default Behavior

Like .filesignore, the .files configuration file is automatically excluded from comparison and sync operations. It will not be copied to destination directories.

Terminal Status Reports

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 file

Usage

Files has three main commands: compare (default), sync, and cp.

Compare Command

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]

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

Exit Codes

  • 0 - Directories are identical
  • 1 - Differences found
  • 2 - Error occurred (invalid directory, access denied, etc.)

Copy Command

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.

Options

  • --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

Example

# Preview what would be copied
files cp /source /backup --dry-run --verbose

# Copy new and modified files
files cp /source /backup --verbose

Sync Command

Synchronize two directories:

files sync <source-directory> <destination-directory> [options]

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

Sync Modes

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 --deletions flag 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-resolution strategy

Conflict Resolution Strategies

  • newest - Keep the file with the most recent modification time (default)
  • source - Always prefer the source file
  • destination - Always prefer the destination file
  • skip - Skip conflicting files, leave both unchanged

Cut Command

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 on PATH, /opt/homebrew/bin or /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, DISCNUMBER and DISCTOTAL from 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, or NN - Performer - Title.ext when a track's performer differs from the album's.

How tracks are cut:

  • A track runs from its INDEX 01 to the next track's INDEX 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 FILE lines, a track ends with its file.
  • If the audio named by FILE is missing, the same name with another audio extension is used (a .wav sheet next to a .flac image), and a sheet with one FILE also matches audio named like the cue sheet.

Options

  • --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-1251 or shift_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

Exit Codes

  • 0 - All tracks were cut
  • 1 - 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

Example

# Preview the track names and ranges
files cut "Album.cue" --dry-run --verbose

# Cut into a separate folder
files cut "Album.cue" -o tracks

Fuzzy Filename Matching

The --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.

How It Works

  • Threshold value: A number from 0.0 to 1.0

    • 1.0 (default): Only exact filename matches
    • 0.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-recursive apply 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

Size Tolerance

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-byte
  • 0.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.

Use Cases

  1. Typo detection: Find files with misspelled names (e.g., "report.txt" vs "reprot.txt")
  2. Version variations: Match files with version numbers (e.g., "file_v1.txt" vs "file_v2.txt")
  3. Renamed files: Identify files that were slightly renamed between directories
  4. Import cleanup: Find near-duplicate files from different sources

Examples

Detect typos in filenames

# Compare with fuzzy matching (80% similarity threshold)
files /backup /current --match-precision 0.8 --verbose

Output shows fuzzy-matched files as "modified":

Modified (2):
  ~ report.txt (matched with: reprot.txt)
  ~ document.txt (matched with: documnet.txt)

Sync with fuzzy matching

# Sync files even if names have minor differences
files sync /source /dest --match-precision 0.8 --verbose

This will:

  • Match "report.txt" (source) with "reprot.txt" (destination)
  • Update the file with correct content
  • Create new "report.txt" in destination

Fuzzy matching with size tolerance

# Match similar filenames and treat similar-sized files as renamed
files compare /dir1 /dir2 --match-precision 0.8 --size-tolerance 0.2

This 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.

Conservative fuzzy matching

# Use higher threshold (90%) for stricter matching
files /dir1 /dir2 --match-precision 0.9

Only 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 on Network Volumes

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 16

To use it every time, put it in the .files of the folder on that volume:

concurrentReads = 16

Examples

Compare Examples

Basic comparison

files /path/to/dir1 /path/to/dir2

Output:

✗ 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

Verbose output

files /path/to/dir1 /path/to/dir2 --verbose

Output:

✗ 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

JSON output

files /path/to/dir1 /path/to/dir2 --format json

Status 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
  }
}

Summary output

files /path/to/dir1 /path/to/dir2 --format summary

Output:

Identical: no
Only in left: 3
Only in right: 2
Modified: 1
Unchanged: 10
Total files: 16

Non-recursive comparison

Compare only top-level files without scanning subdirectories:

files /path/to/dir1 /path/to/dir2 --no-recursive

Use in scripts

#!/bin/bash

if files /backup /current --format summary; then
    echo "Backup is up to date"
else
    echo "Backup needs updating"
fi

Sync Examples

Basic one-way sync (without deletions)

Copy and update files from source to destination (extra files in destination are kept):

files sync /source/dir /backup/dir --dry-run --verbose

Output:

🔍 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 --verbose

Output:

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

One-way sync with deletions

Mirror source to destination exactly (deletes extra files in destination):

files sync /source/dir /backup/dir --deletions --dry-run --verbose

Output:

🔍 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 --verbose

Output:

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

Two-way sync with newest conflict resolution

Synchronize two directories bidirectionally, keeping the newest version of conflicting files:

files sync /dir1 /dir2 --two-way --conflict-resolution newest --verbose

Output:

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

Two-way sync preferring source

Always prefer the source directory for conflicts:

files sync /source /dest --two-way --conflict-resolution source

Two-way sync skipping conflicts

Sync unique files but skip conflicting files:

files sync /dir1 /dir2 --two-way --conflict-resolution skip --verbose

JSON output for automation

files sync /source /dest --dry-run --format json

Output:

{
  "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
  }
}

Backup automation script

#!/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
fi

Bidirectional project sync

Keep two working directories in sync:

# Sync laptop and desktop project directories
files sync ~/projects/myapp /mnt/desktop/projects/myapp --two-way --conflict-resolution newest

Building

Building 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

Benchmarks

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 benchmark

Installation

You 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/files

LICENSE: MIT

About

Files Toolbox

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages