{"id":31033391,"url":"https://github.com/nicejade/fine-directory-curator","last_synced_at":"2025-09-14T01:52:24.499Z","repository":{"id":312039101,"uuid":"1040854490","full_name":"nicejade/fine-directory-curator","owner":"nicejade","description":"A Rust-powered CLI tool for elegantly organizing and curating files in macOS directories, starting with the Downloads folder. Seamlessly sort, categorize, and manage contents across any specified path for a streamlined, clutter-free workflow.","archived":false,"fork":false,"pushed_at":"2025-08-28T05:57:24.000Z","size":18,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-28T12:14:26.546Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nicejade.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-19T15:50:24.000Z","updated_at":"2025-08-28T05:57:27.000Z","dependencies_parsed_at":"2025-08-28T12:16:20.521Z","dependency_job_id":"3aa4e0f4-efac-4c86-91ad-e4f56097bbaf","html_url":"https://github.com/nicejade/fine-directory-curator","commit_stats":null,"previous_names":["nicejade/fine-directory-curator"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/nicejade/fine-directory-curator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicejade%2Ffine-directory-curator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicejade%2Ffine-directory-curator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicejade%2Ffine-directory-curator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicejade%2Ffine-directory-curator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nicejade","download_url":"https://codeload.github.com/nicejade/fine-directory-curator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicejade%2Ffine-directory-curator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275051639,"owners_count":25396977,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-13T02:00:10.085Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-14T01:52:21.794Z","updated_at":"2025-09-14T01:52:24.462Z","avatar_url":"https://github.com/nicejade.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fine Directory Curator (fdc)\n\n🗂️ A fast, elegant Rust CLI for keeping your macOS \u0026 Linux folders tidy (Windows support planned).  \nIt sorts first-level items by **year** and **type**, avoids overwrite collisions, preserves top-level structure, and lets you **preview** before doing anything destructive.\n\n\u003e TL;DR: `cargo install fine-directory-curator` → `fdc --dry-run` → review → `fdc`  \n\u003e No drama, no duplicates, no \"where-did-that-download-go?\" energy.\n\n---\n\n## Table of Contents\n- [Why fdc?](#why-fdc)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [CLI Reference](#cli-reference)\n  - [Commands](#commands)\n  - [Global Flags](#global-flags)\n  - [Examples](#examples)\n- [Configuration](#configuration)\n  - [File layout \u0026 rules](#file-layout--rules)\n  - [Extension categories](#extension-categories)\n- [Behavior \u0026 Guarantees](#behavior--guarantees)\n- [Operating System Support](#operating-system-support)\n- [Development](#development)\n- [Troubleshooting \u0026 FAQ](#troubleshooting--faq)\n- [Roadmap](#roadmap)\n- [License](#license)\n\n---\n\n## Why fdc?\n\nBecause the messy reality is: **Downloads** fills up, collisions happen, and recursive tools are risky.  \n**fdc** is opinionated on purpose:\n- **Shallow \u0026 safe**: Only the **first level** of the source directory is organized. Directories are moved whole; no deep traversal surprises.\n- **Year-first**: Time is the best primary key for \"where does this belong?\"\n- **Non-overwriting**: Uses `name (1).ext`, `name (2).ext`, … instead of clobbering.\n- **Preview-first**: `--dry-run` to see exactly what will change.\n- **Fast \u0026 portable**: Written in Rust, runs great on macOS and Linux.\n\n---\n\n## Installation\n\n### From crates.io (recommended)\n\n```bash\ncargo install fine-directory-curator\n# binary will be available on PATH as:\nfdc\n```\n\n\u003e Note: Package name is `fine-directory-curator`, executable is `fdc`.\n\n### Build from source\n\n```bash\n# in repo root\ncargo build --release\n# binary:\n./target/release/fdc\n```\n\n---\n\n## Quick Start\n\n```bash\n# See help\nfdc --help\n\n# Use defaults (source: ~/Downloads, target: ~/Documents/Matrixs)\nfdc\n\n# Dry run (no changes)\nfdc --dry-run\n\n# Custom source \u0026 target\nfdc -s ~/Downloads -t ~/Documents/Matrixs\n\n# Set source path in config only (no execution)\nfdc -s ~/Downloads\n\n# Verbose logging (stackable)\nfdc -v\nfdc -vv\n```\n\n---\n\n## CLI Reference\n\n### Commands\n\n| Command | Alias | Purpose | Notes |\n|---|---|---|---|\n| `fdc` | — | Run organizer with current config (or defaults) | Use with flags to customize run |\n| `fdc init-config` | — | Create a default config file | No overwrite; prompts if exists |\n| `fdc config` | — | Print resolved configuration | Useful for debugging |\n| `fdc set-source \u003cPATH\u003e` | — | Set source directory in config | Updates config file only |\n| `fdc set-target \u003cPATH\u003e` | — | Set target root in config | Updates config file only |\n| `fdc --help` | `-h` | Show help | — |\n| `fdc --version` | `-V` | Show version | SemVer |\n\n### Global Flags\n\n| Flag | Alias | Type | Default | Effect | Example |\n|---|---|---|---|---|---|\n| `--dry-run` | — | bool | `false` | Plan only; print actions; do not modify FS | `fdc --dry-run` |\n| `--source \u003cDIR\u003e` | `-s` | path | `~/Downloads` | Override source directory | `fdc -s ~/Desktop` |\n| `--target \u003cDIR\u003e` | `-t` | path | `~/Documents/Matrixs` | Override target root | `fdc -t ~/Archive` |\n| `--verbose` | `-v` | count | `0` | Increase log detail (stackable) | `fdc -vv` |\n| `--help` | `-h` | — | — | Show usage | `fdc -h` |\n| `--version` | `-V` | — | — | Show version | `fdc -V` |\n\n\u003e **Smart Flag Behavior**: When only `-s` is provided (without `-t`, `--dry-run`, or `-v`), fdc will only update the config file and not execute any file operations.\n\n### Examples\n\n| Goal | Command |\n|---|---|\n| Preview what tomorrow's cleanup would do | `fdc --dry-run` |\n| Move only your current Downloads into your structured vault | `fdc` |\n| Use a custom target root | `fdc -t ~/Documents/Matrixs` |\n| Run from a different source folder | `fdc -s ~/Desktop` |\n| Set source path in config only | `fdc -s ~/Desktop` |\n| Set source path in config only (explicit) | `fdc set-source ~/Desktop` |\n| Set target in config only | `fdc set-target ~/Archive` |\n| Turn on detailed logs | `fdc -vv` |\n| Initialize (or re-check) your config file | `fdc init-config` ; `fdc config` |\n\n---\n\n## Configuration\n\nOn first run, fdc writes a default config to:\n\n- **macOS**: `~/Library/Application Support/fine-directory-curator/config.toml`  \n- **Linux**: `~/.config/fine-directory-curator/config.toml`\n\n\u003e Prefer `fdc init-config` if you want to create it proactively.\n\n### Sample `config.toml`\n```toml\nsource_dir = \"~/Downloads\"\ntarget_dir = \"~/Documents/Matrixs\"\n\n[sort_rule]\n# Sorting priority; left to right\norder = [\"year\", \"category\"]\n\n# Map specific extensions to custom categories (optional)\n[extension_overrides]\n# xmind = \"mindmaps\"\n# heic  = \"images\"\n```\n\n### File layout \u0026 rules\n\n- **Year** comes first, derived by:\n  1) file **creation time**;  \n  2) fallback to **modification time**;  \n  3) fallback to **current year** if neither is available.\n- **Category** comes second (see below).\n- **Structure example**:\n  ```\n  \u003ctarget_dir\u003e/\n    2025/\n      images/\n      documents/\n      videos/\n      ...\n  ```\n\n### Extension categories\nfdc maps extensions (case-insensitive) to these buckets:\n\n- `images`, `pdfs`, `videos`, `audio`, `archives`,  \n  `documents`, `spreadsheets`, `presentations`,  \n  `code`, `design`, `mindmaps`, `executables`,  \n  `installers`, `fonts`, `others`, `directory`\n\n\u003e Directories are **not** traversed deeply; they are treated as a single item and moved under `directory/`.\n\n---\n\n## Behavior \u0026 Guarantees\n\n- **Non-overwrite strategy**: if a target path exists, fdc writes `name (1).ext`, `name (2).ext`, … until it finds a free slot.\n- **Shallow operation**: only first-level entries in `source_dir` are processed.\n- **Cross-volume safe**: moves across filesystems are done as **copy + delete**.\n- **Idempotent-ish**: running again won't duplicate files in-place thanks to non-overwrite naming.\n- **Safety first**: Always start with `--dry-run` on new setups.\n\n---\n\n## Operating System Support\n\n| OS | Status | Notes |\n|---|---|---|\n| **macOS** | ✅ Supported | Tested on Apple Silicon \u0026 Intel |\n| **Linux** | ✅ Supported | XDG config path used by default |\n| **Windows** | 🛤️ Planned | Path semantics \u0026 metadata handling to be added |\n\n\u003e macOS users: if organizing outside your home folder, you may need to grant Terminal (or your shell) **Full Disk Access**.\n\n---\n\n## Development\n\nA lean workflow that keeps quality high and iteration fast.\n\n### Prerequisites\n- Rust 1.75+ (via `rustup`)\n- `cargo fmt`, `clippy`, and `cargo test`\n\n### Common tasks\n```bash\n# Format\ncargo fmt\n\n# Lint strictly\ncargo clippy -- -D warnings\n\n# Unit \u0026 integration tests\ncargo test\n\n# Release build\ncargo build --release\n```\n\n### Suggested developer UX (optional but recommended)\n- Use a `justfile` or `Makefile` for one-liners:\n  ```makefile\n  build: ; cargo build --release\n  check: ; cargo fmt --check \u0026\u0026 cargo clippy -- -D warnings \u0026\u0026 cargo test\n  release: check build\n  ```\n- Add a pre-commit hook:\n  ```bash\n  # .git/hooks/pre-commit\n  cargo fmt -- --check \u0026\u0026\n  cargo clippy -- -D warnings \u0026\u0026\n  cargo test\n  ```\n- Versioning \u0026 publishing: use `cargo-release` for tagging, changelogs, and `cargo publish` hygiene.\n\n---\n\n## Troubleshooting \u0026 FAQ\n\n**Q: Nothing moved. What gives?**  \nA: Run with `-vv` to inspect decisions. Ensure the source directory contains items at the top level. fdc does not recurse into subfolders.\n\n**Q: Why “year” first?**  \nA: Time is universal across file types and workflows. It keeps archives navigable even when categories blur.\n\n**Q: Can I customize categories?**  \nA: Yes, with `[extension_overrides]` in `config.toml`. Unknown extensions go to `others/`.\n\n**Q: Is `--dry-run` truly non-destructive?**  \nA: Yes. It only prints the plan; no filesystem writes occur.\n\n**Q: Handling duplicates?**  \nA: fdc never overwrites. It picks the next available `name (N).ext`.\n\n**Q: Will fdc change file metadata?**  \nA: Moves generally preserve metadata; cross-device copy + delete may differ per FS. Original timestamps are used for routing; they are not rewritten.\n\n---\n\n## Roadmap\n\n- ✅ macOS \u0026 Linux parity  \n- ⏭️ Windows support (path, timestamps, alternate data streams)  \n- ⏭️ Configurable naming templates (e.g., `YYYY/category` vs `category/YYYY`)  \n- ⏭️ Include/ignore patterns (e.g., `.fdcignore`)  \n- ⏭️ Summary report output (`--report json|markdown`)  \n- ⏭️ Dry-run diff to file (`--plan \u003cpath\u003e`)  \n\n\u003e Have opinions? Open an issue or PR—let’s keep the filesystem civilized together.\n\n---\n\n## License\n\n[MIT](http://opensource.org/licenses/MIT) © 2025–present, [逍遥自在轩](https://www.niceshare.site/)。","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicejade%2Ffine-directory-curator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnicejade%2Ffine-directory-curator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicejade%2Ffine-directory-curator/lists"}