FolderSorter - Safe macOS File Organizer

Open-source, local-first macOS file organizer and Downloads cleaner with safe preview, undo, visual rules, a SwiftUI GUI, and a cross-platform Python CLI.

開源、本機處理的 macOS 檔案整理器與 Downloads 清理工具，支援安全預覽、復原、視覺化規則、SwiftUI GUI 與跨平台 Python CLI。

English-only | 繁體中文獨立版

English

FolderSorter is built for the common file clutter problem: a messy Downloads folder, Desktop, screenshots pile, and random PDFs, ZIPs, DMGs, videos, and images. Unlike tools that immediately move files, FolderSorter previews every operation first and can undo the last cleanup.

The goal is not to be the most powerful automation tool; it is to be the file organizer users feel safe pressing Apply on.

macOS File Organizer Features

Downloads and Desktop cleanup: organize screenshots, PDFs, archives, installers, photos, videos, and code.
Preview-first cleanup: drag files or folders in, inspect the plan, then apply.
One-click undo: every applied cleanup writes a local transaction record.
Common Mac defaults: Images, Videos, Documents, Archives, Installers, Audio, Code, and Screenshots.
Conflict control: automatically rename, skip, or replace same-name files.
Rules you can read: rules can be imported and exported as JSON.
GUI + CLI: a simple Mac app for everyday use and a pure Python foldersorter CLI for automation.
Bilingual interface: follow system language, English, or Traditional Chinese.
Local-first privacy: no uploads, no analytics, no network feature.

Common macOS File Organization Use Cases

Downloads folder organizer: sort JPG, PNG, PDF, ZIP, RAR, 7z, DMG, PKG, MP4, and MOV files into clear folders.
Desktop and screenshot organizer: separate screenshots from other images without deleting originals.
Photo, video, and document sorter: route common media and office files with readable visual rules.
Safe folder cleanup: preview every copy or move, handle filename conflicts, and undo the latest cleanup.

Requirements

Downloaded Mac app: macOS 14 or newer
Building from source: Xcode Command Line Tools or Xcode with SwiftPM

Download The Mac App

Download FolderSorter-0.2.0.dmg from the latest GitHub release.

The current macOS app build is unsigned. On first launch, macOS may require right-clicking the app and choosing Open.

Run The App

./script/build_and_run.sh

The generated app bundle is written to:

dist/FolderSorter.app

Install The Cross-Platform CLI With pip

python3 -m pip install foldersorter
foldersorter --help

The pip package is implemented in Python and works on macOS, Windows, and Linux. It does not require Swift, Xcode, or Xcode Command Line Tools.

Use The App

Open the app.
Choose an output folder, or use the default Desktop C folder.
Drag in a folder, click Downloads, click Desktop, or choose files manually.
Review the preview.
Click Start Sorting only when the plan looks right.
Use Undo to revert the latest cleanup.

The default mode is copy, so original files stay in place. Move mode is available when you want a real cleanup.

The app includes a language picker with System, English, and 繁體中文.

CLI

Preview only:

swift run foldersorter --input ~/Downloads --output ~/Desktop/C

Apply the preview:

swift run foldersorter --input ~/Downloads --output ~/Desktop/C --apply

Move instead of copy:

swift run foldersorter --input ~/Downloads --output ~/Desktop/C --move --apply

Use exported or example rules:

swift run foldersorter \
  --input ~/Downloads \
  --output ~/Desktop/C \
  --rules Examples/general-mac-cleanup.rules.json

Undo the latest applied cleanup:

swift run foldersorter --undo

Rule Format

Rules are evaluated in order. A rule matches when all filled conditions match. For example, the screenshot rule checks both file extension and filename tokens:

{
  "extensionsText": "png, jpg, jpeg",
  "nameContainsText": "screenshot, 截圖",
  "folderName": "Screenshots"
}

Development

Run tests:

swift test

Build all products:

swift build

Generate app icons:

swift script/generate_icon.swift

Project Positioning

FolderSorter is not trying to clone Hazel or organize. The goal is a safer, simpler, transparent organizer for the broadest Mac audience:

easier than complex automation tools,
safer than one-shot cleaners,
more transparent than closed-source apps,
more approachable than CLI-only organizers.

The product strategy is documented in PRODUCT_STRATEGY.md.

Next Priorities

Trust-first preview: show category summary, before / after paths, matching reasons, and risk notes before Apply.
Undo and cleanup reports: make the latest transaction inspectable, previewable, and easy to restore.
Signed release: the GitHub release now includes .zip and .dmg; the next packaging step is signing and notarization.
Stronger GUI rules: add visual conditions for file size, dates, screenshots, duplicates, and broad file types.

Help This Project Grow

FolderSorter is positioned as a macOS Downloads cleaner, screenshot organizer, and local-first file management utility for non-technical Mac users first, while still keeping CLI and JSON rules for power users.

Star or share the repository if the preview-first workflow solves a real cleanup problem.
Use the included UI screenshot when writing posts or issue discussions.
Use Media/foldersorter-social-preview.jpg as the GitHub social preview image.
See DISCOVERABILITY.md for the launch checklist and posting copy.

繁體中文

FolderSorter 解決的是最常見的檔案混亂問題：Downloads 爆滿、桌面塞滿截圖、PDF、ZIP、DMG、影片、圖片和各種臨時檔。FolderSorter 不會一開始就移動檔案，而是先產生整理預覽，讓你確認之後再套用；套用後也能復原上一筆整理。

它要追求的不是最強自動化，而是讓一般使用者最敢按下整理。

macOS 檔案整理功能

整理 Downloads 與桌面：分類截圖、PDF、壓縮檔、安裝檔、照片、影片與程式碼。
整理前先預覽：拖入檔案或資料夾，先看完整計畫，再決定是否套用。
一鍵復原：每次套用整理都會留下本機 transaction 紀錄。
一般 Mac 預設分類：Screenshots、Images、Videos、Documents、Archives、Installers、Audio、Code。
同名衝突控制：自動改名、略過同名、或取代同名。
規則透明：分類規則可以匯入與匯出成 JSON。
GUI + CLI：一般 Mac 使用者用 SwiftUI app，進階或跨平台使用者可用純 Python foldersorter CLI。
雙語介面：可跟隨系統語言，也可手動選 English 或繁體中文。
本機優先隱私：不會上傳檔案、檔名、規則，也沒有分析追蹤。

常見 macOS 檔案整理用途

Downloads 資料夾整理器：把 JPG、PNG、PDF、ZIP、RAR、7z、DMG、PKG、MP4、MOV 分到清楚的資料夾。
桌面與截圖整理器：把截圖和其他圖片分開整理，不刪除原始檔案。
照片、影片、文件分類器：使用容易理解的視覺規則整理常見媒體與辦公文件。
安全清理資料夾：每次 copy 或 move 前先預覽，處理同名衝突，並可復原最近一次整理。

系統需求

直接下載 Mac app：macOS 14 或更新版本
從原始碼建置：Xcode Command Line Tools 或包含 SwiftPM 的 Xcode

下載 Mac App

可以從最新 GitHub Release 下載 FolderSorter-0.2.0.dmg。

目前 macOS app 尚未簽章。第一次開啟時，macOS 可能會要求你對 app 按右鍵後選擇 打開。

執行 App

./script/build_and_run.sh

產生的 app bundle 會放在：

dist/FolderSorter.app

使用 pip 安裝跨平台 CLI

python3 -m pip install foldersorter
foldersorter --help

pip 套件是純 Python CLI，可在 macOS、Windows、Linux 使用，不需要 Swift、 Xcode 或 Xcode Command Line Tools。

使用方式

打開 app。
選擇輸出資料夾，或使用預設的桌面 C 資料夾。
拖入資料夾、點 Downloads、點 Desktop，或手動選擇檔案。
檢查整理預覽。
確認計畫沒問題後再按 開始整理。
需要回復時按 復原，可復原上一筆整理。

預設模式是複製，所以原始檔案會留在原處。若你想真正清理原資料夾，可以切換到移動模式。

app 左側有語言選單，可選 System / 跟隨系統、English 或 繁體中文。

CLI

只預覽，不移動或複製檔案：

swift run foldersorter --input ~/Downloads --output ~/Desktop/C

套用預覽：

swift run foldersorter --input ~/Downloads --output ~/Desktop/C --apply

改成移動模式：

swift run foldersorter --input ~/Downloads --output ~/Desktop/C --move --apply

使用匯出的規則或範例規則：

swift run foldersorter \
  --input ~/Downloads \
  --output ~/Desktop/C \
  --rules Examples/general-mac-cleanup.rules.json

復原上一筆已套用的整理：

swift run foldersorter --undo

規則格式

規則會依照順序檢查。每條規則中有填寫的條件都必須符合。例如截圖規則會同時檢查副檔名和檔名關鍵字：

{
  "extensionsText": "png, jpg, jpeg",
  "nameContainsText": "screenshot, 截圖",
  "folderName": "Screenshots"
}

開發

執行測試：

swift test

建置所有 products：

swift build

產生 app icon：

swift script/generate_icon.swift

專案定位

FolderSorter 不是要複製 Hazel 或 organize。它的目標是做出更安全、更簡單、更透明，適合最大多數 Mac 使用者的檔案整理器：

比複雜自動化工具更容易上手；
比一次性清理工具更安全；
比閉源工具更透明；
比純 CLI 工具更適合一般使用者。

產品策略整理在 PRODUCT_STRATEGY.zh-TW.md。

下一步優先事項

信任優先預覽：Apply 前顯示分類總覽、Before / After、命中原因與風險提示。
Undo 與整理報告：讓最近一次 transaction 可以檢視、預覽復原、清楚復原。
簽章版本：GitHub Release 已提供 .zip 與 .dmg；下一個 packaging 重點是 signing 與 notarization。
強化 GUI 規則：加入檔案大小、日期、截圖、重複檔、檔案大類型等視覺化條件。

幫助更多人看見

FolderSorter 的定位是給一般 Mac 使用者的 Downloads 清理工具、截圖整理器、本機優先檔案管理工具；同時保留 CLI 與 JSON 規則給進階使用者。

如果預覽優先的整理流程真的解決你的問題，可以 star 或分享這個 repo。
寫文章、貼文或 issue 討論時，可以直接使用 repo 內的 UI 展示圖。
Media/foldersorter-social-preview.jpg 可作為 GitHub social preview 圖片。
DISCOVERABILITY.md 裡有 launch checklist 與中英文推廣文案。

License / 授權

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.codex/environments		.codex/environments
.github/workflows		.github/workflows
Assets		Assets
Examples		Examples
Media		Media
Sources		Sources
Tests/FolderSorterCoreTests		Tests/FolderSorterCoreTests
python/foldersorter		python/foldersorter
python_tests		python_tests
script		script
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
DISCOVERABILITY.md		DISCOVERABILITY.md
LICENSE		LICENSE
PRIVACY.md		PRIVACY.md
PRIVACY.zh-TW.md		PRIVACY.zh-TW.md
PRODUCT_STRATEGY.md		PRODUCT_STRATEGY.md
PRODUCT_STRATEGY.zh-TW.md		PRODUCT_STRATEGY.zh-TW.md
PYPI.md		PYPI.md
Package.swift		Package.swift
README.en.md		README.en.md
README.md		README.md
README.zh-TW.md		README.zh-TW.md
ROADMAP.md		ROADMAP.md
ROADMAP.zh-TW.md		ROADMAP.zh-TW.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

FolderSorter - Safe macOS File Organizer

English

macOS File Organizer Features

Common macOS File Organization Use Cases

Requirements

Download The Mac App

Run The App

Install The Cross-Platform CLI With pip

Use The App

CLI

Rule Format

Development

Project Positioning

Next Priorities

Help This Project Grow

繁體中文

macOS 檔案整理功能

常見 macOS 檔案整理用途

系統需求

下載 Mac App

執行 App

使用 pip 安裝跨平台 CLI

使用方式

CLI

規則格式

開發

專案定位

下一步優先事項

幫助更多人看見

License / 授權

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages