FileSearcher-Brit

Cross-Platform File Search Utility with Timestamp Filtering and Multiple Output Formats

FileSearcher-Brit is a high-performance command-line tool for locating files by modification timestamp across directory structures. Built with Go for speed and cross-platform compatibility.

Note

The Problem: You know you worked on that .sh file in March 2024, and it's somewhere in your ~/projects folder but you have 50+ project subdirectories and don't remember which one.

The Solution: FileSearcher-Brit recursively scans entire directory trees by modification date. Point it at ~/projects, specify March 2024, and it finds every matching file across all subdirectories - with support for partial date matching (year only, month only, or exact date).

Table of Contents

• Overview
• Comparison with Existing Tools
• Features
• Requirements
• Installation
• Usage
• Date Filtering Logic
• Performance
• Technical Details
• License
• Contact

Overview

FileSearcher-Brit combines flexible timestamp filtering with efficient directory traversal to quickly locate files modified on specific dates. It provides:

• Deep scan with recursive directory traversal
• Granular date filtering (day, month, year, or partial combinations)
• Extension-based filtering with O(1) hash map lookup
• Multiple output formats (JSON, Markdown, tabular)
• Live scanning progress with color-coded feedback
• Human-readable file sizes and professional formatting

Comparison with Existing Tools

Feature	FileSearcher-Brit	find (Linux/macOS)	dir (Windows CMD)	Generic Tools
Cross-Platform	✅ Windows/macOS/Linux	❌ Linux/macOS only	❌ Windows only	⚠️ Varies
Structured Output	✅ JSON + Markdown	❌ Requires pipes	❌ Not supported	❌ Rare
Date Partial Match	✅ Year/Month/Day combos	⚠️ Limited	❌ Only ranges	❌ Not supported
Extension Filter	✅ O(1) hash lookup	⚠️ Pattern matching	❌ Basic wildcards	⚠️ O(n) loops
Live Progress	✅ Real-time feedback	❌ Silent	❌ Silent	❌ Rare
Human Sizes	✅ KB/MB/GB	❌ Bytes only	❌ Bytes only	⚠️ Varies
Error Handling	✅ Skips & continues	⚠️ Depends on flags	❌ Stops on errors	⚠️ Basic
Learning Curve	✅ Simple flags	⚠️ Complex syntax	⚠️ Limited	⚠️ Varies

When to use FileSearcher-Brit:

• Cross-platform file auditing (same tool on Windows/macOS/Linux)
• Need structured output (JSON/Markdown) for reports or automation
• Want modern UX (colors, live progress, readable formatting)
• Timestamp-based file discovery with partial date matching
• CI/CD integration requiring consistent behavior across OS

When to use find (Linux/macOS):

• Already working exclusively on Linux/macOS
• Need advanced POSIX features (exec, xargs integration)
• Comfortable with complex command-line syntax

When to use dir (Windows CMD):

• Simple directory listing on Windows only
• Basic date range filtering is sufficient
• Don't need structured exports

Features

Core Capabilities:

• Deep scan with recursive directory traversal using filepath.WalkDir
• Timestamp-based filtering (day, month, year, or partial combinations)
• Extension filtering with comma-separated support and O(1) lookup
• Multiple output formats (JSON, Markdown, tabular)
• Graceful error handling (skips inaccessible directories)
• Cross-platform path handling (Windows/macOS/Linux)

Advanced Features:

• Live scanning progress with real-time file counts
• ANSI color-coded terminal output with atomic cleanup
• Human-readable file sizes (B, KB, MB, GB)
• Professional ASCII art headers and summary boxes
• Automatic output filename generation based on extensions
• Permission error recovery without scan interruption
• UI throttling (updates every 50 files) to prevent I/O bottlenecks

Requirements

• Go 1.16 or higher

Installation

Option 1: Download Pre-compiled Binary (Recommended)

Don't have Go installed? Download the pre-compiled binary for your platform from the Releases page.

# Linux/macOS
chmod +x filesearch
./filesearch -dir . -y 2024 -ex go,py -o json

# Windows
filesearch.exe -dir . -y 2024 -ex go,py -o json

Option 2: Build from Source

# Clone the repository
git clone https://github.com/gigachad80/FileSearcher-Brit
cd FileSearcher-Brit

# Build the binary
go build -o filesearch

# Run the tool
./filesearch -dir . -y 2024 -ex go,py -o json

Option 3: Build for Multiple Platforms

# Linux
GOOS=linux GOARCH=amd64 go build -o filesearch-linux

# macOS
GOOS=darwin GOARCH=amd64 go build -o filesearch-macos

# Windows
GOOS=windows GOARCH=amd64 go build -o filesearch.exe

Usage

Basic Syntax

filesearch [flags]

Flags

Flag	Type	Description	Example
-dir	string	Target directory path (default: current directory)	-dir /home/user/projects
-dt	int	Day filter (1-31)	-dt 15
-m	int	Month filter (1-12)	-m 1
-y	int	Year filter	-y 2024
-all	string	Complete date in DD/M/YYYY format	-all 15/1/2024
-r	bool	Enable recursive directory scan	-r
-ex	string	File extensions (comma-separated, no spaces)	-ex go,py,js
-o	string	Output format: tabular, json, or md (default: tabular)	-o json

Examples

# Find all Go files modified in January 2024 (recursive)
./filesearch -dir . -m 1 -y 2024 -ex go -r -o json

# Find files modified on specific date
./filesearch -dir /var/logs -all 15/1/2024 -r -o md

# Search current directory for Python files (any modification date)
./filesearch -dir . -ex py -o tabular

# Multiple extensions with year filter
./filesearch -dir ~/projects -y 2023 -ex go,js,py,java -r -o json

# Partial match: All January files (any year)
./filesearch -dir ~/documents -m 1 -ex txt,md -r -o json

Command Line Help

./filesearch
# Displays usage information and available flags

Date Filtering Logic

The tool supports flexible date filtering with partial matching capabilities:

Flags Used	Matching Logic	Example
-y 2024	Partial: All files from 2024 (any month, any day)	Entire year 2024
-m 1	Partial: All January files (any year, any day)	All January files from 2020-2026
-m 1 -y 2024	Partial: All files modified in January 2024 (any day)	January 1-31, 2024
-dt 15 -m 1 -y 2024	Exact: Files modified on exactly January 15, 2024	Only 2024-01-15
-all 15/1/2024	Exact: Files modified on exactly January 15, 2024	Only 2024-01-15 (overrides -dt/-m/-y)

Note

Key Feature: Unlike most tools, FileSearcher-Brit supports partial date matching - you can search by year alone, month alone, or any combination. The -all flag takes precedence over individual flags when specified.

Performance

Optimization Details

Extension Matching: O(1) hash map lookup

allowedExts := map[string]bool{".go": true, ".py": true}
if allowedExts[ext] { /* instant lookup */ }

Directory Traversal: Go's optimized filepath.WalkDir

• C-optimized for performance
• Efficient memory usage
• Automatic error recovery

UI Throttling: Progress updates are throttled to every 50 files to ensure terminal I/O doesn't bottleneck the Go runtime's scanning speed.

Technical Details

Recursive Scanning

Uses Go's built-in filepath.WalkDir for efficient depth-first traversal:

filepath.WalkDir(dir, func(path string, d os.DirEntry, err error) error {
    if err != nil {
        return filepath.SkipDir // Skip inaccessible directories
    }
    // Process files...
})

Handles:

• Permission denied errors (skips and continues)
• Nested directory structures of any depth
• Symbolic links
• Cross-platform path separators

Atomic UI Cleanup: Uses ANSI escape sequences (\033[2K) to clear the live-scan buffer upon completion, ensuring a clean transition to the summary report.

License

This project is licensed under the GNU GPL 3.0 License - see the LICENSE file for details.

Contact

Email: pookielinuxuser@tutamail.com

---

Built with Go - Efficient file searching for timestamp-based auditing.

---

First Released: January 31, 2026
Last Updated: January 31, 2026