Skip to content

Commit 2a94fd8

Browse files
author
Stew Alexander
committed
Refactor README: improve flow, remove duplication, enhance clarity
- Reorganize sections for better logical flow (Quick Start first) - Remove redundant 'At a Glance' section - Consolidate duplicate macOS download links and Windows instructions - Streamline content while maintaining all essential information - Improve readability and scannability - Reduce overall length by ~50 lines without losing information
1 parent c038c31 commit 2a94fd8

1 file changed

Lines changed: 91 additions & 165 deletions

File tree

‎README.md‎

Lines changed: 91 additions & 165 deletions
Original file line numberDiff line numberDiff line change
@@ -1,196 +1,152 @@
11
# Easy File Cleanup
22

3-
> **⚠️ Important Security Notice (Version 4.0)**: The pre-built Windows `.exe` file has been removed due to security violations detected by Windows 11 and Sentinel One. Windows users should build the executable from source (see [Building Windows Releases](#building-windows-releases) below) or use the CLI/TUI interfaces directly with Python.
3+
> **⚠️ Important Security Notice (Version 4.0)**: The pre-built Windows `.exe` file has been removed due to security violations detected by Windows 11 and Sentinel One. Windows users should build the executable from source (see [Building Windows Releases](#building-windows-releases)) or use the CLI/TUI interfaces directly with Python.
44
55
Organizes files by extension into dedicated folders to quickly clean up messy directories (like Downloads) on any OS. **Files are moved only within your chosen directory, and an `organization_log.txt` tracks every change so you can review what happened.**
66

7-
**Why this tool?**
7+
## Why This Tool?
8+
89
- **No network access** — runs entirely locally, your files never leave your machine
910
- **Reversible** — complete log file tracks every move for easy review and undo
1011
- **Automation-friendly** — works great in cron jobs and CI/CD pipelines
1112
- **Multiple interfaces** — choose web UI, terminal UI, or command-line automation
1213
- **Cross-platform** — works on Windows, macOS, and Linux
1314

14-
## At a Glance
15-
16-
- **What it does**: Automatically sorts files into folders by their extension (pdf/, jpg/, txt/, etc.)
17-
- **Who it's for**: Non-technical users (web browser UI), terminal users (full-screen keyboard interface), and developers/power users (automation/cron/CI)
18-
- **Quick start**: Recommended for most: download and double-click (no Python/Flask needed)
19-
- macOS: [Mac-File-Cleanup.zip](https://github.com/StewAlexander-com/File_Cleanup/releases/download/v4.0/Mac-File-Cleanup.zip) (unzip, then double-click the `.app`)
20-
⚠️ **First run**: If you see a security warning, see [First Run Instructions (macOS)](#first-run-instructions-macos) below.
21-
- Windows: Build from source (see [Building Windows Releases](#building-windows-releases)) or use CLI/TUI directly
22-
- CLI (web UI):
23-
`python3 Easy-File-Cleanup.py --html` # needs Flask installed
24-
- CLI (organize a folder):
25-
`python3 Easy-File-Cleanup.py ~/Downloads`
26-
27-
## Table of Contents
28-
29-
- [Easy File Cleanup](#easy-file-cleanup)
30-
- [At a Glance](#at-a-glance)
31-
- [Table of Contents](#table-of-contents)
32-
- [Installation](#installation)
33-
- [Quick Start](#quick-start)
34-
- [Web Interface (CLI)](#web-interface-cli)
35-
- [Terminal Interface (TUI)](#terminal-interface-tui)
36-
- [Command Line (Automation)](#command-line-automation)
37-
- [Desktop Apps (PyInstaller)](#desktop-apps-pyinstaller)
38-
- [First Run Instructions (macOS)](#first-run-instructions-macos)
39-
- [Features](#features)
40-
- [Core Functionality](#core-functionality)
41-
- [Interface Options](#interface-options)
42-
- [Automation](#automation)
43-
- [How It Works](#how-it-works)
44-
- [Usage](#usage)
45-
- [Basic Command Line](#basic-command-line)
46-
- [Interactive Mode](#interactive-mode)
47-
- [Available Flags](#available-flags)
48-
- [Automation \& Scripting](#automation--scripting)
49-
- [Testing](#testing)
50-
- [Documentation](#documentation)
51-
- [Contributing](#contributing)
52-
- [License](#license)
53-
- [Contact](#contact)
15+
## Quick Start
5416

55-
## Installation
17+
### Option 1: Desktop App (Recommended for most users)
5618

57-
**Requirements**: Python 3.6+
19+
**macOS**: Download [Mac-File-Cleanup.zip](https://github.com/StewAlexander-com/File_Cleanup/releases/download/v4.0/Mac-File-Cleanup.zip), unzip, and double-click `Mac File Cleanup.app`
20+
- ⚠️ **First run**: If you see a security warning, see [First Run Instructions (macOS)](#first-run-instructions-macos) below
5821

59-
```bash
60-
git clone https://github.com/StewAlexander-com/File_Cleanup.git
61-
cd File_Cleanup
62-
63-
chmod +x Easy-File-Cleanup.py
64-
65-
# Only needed for CLI --html; desktop apps already bundle Flask
66-
pip install Flask
22+
**Windows**: Pre-built executables are not available. Build from source (see [Building Windows Releases](#building-windows-releases)) or use Python directly:
23+
```powershell
24+
python Easy-File-Cleanup.py --html
6725
```
6826

69-
## Quick Start
70-
71-
Fastest path: download the desktop app for your OS (no Python/Flask needed):
72-
- macOS: [Mac-File-Cleanup.zip](https://github.com/StewAlexander-com/File_Cleanup/releases/download/v4.0/Mac-File-Cleanup.zip) — unzip, then double-click `Mac File Cleanup.app`
73-
⚠️ **First run**: If you see a security warning, see [First Run Instructions (macOS)](#first-run-instructions-macos) below.
74-
- Windows: See [Building Windows Releases](#building-windows-releases) below to build from source, or use the CLI/TUI interfaces directly
75-
76-
Prefer the CLI instead? Use the commands below.
27+
### Option 2: Command Line
7728

78-
### Web Interface (CLI)
79-
Runs in your browser with a visual directory tree. Requires Flask to be installed:
29+
**Web Interface** (requires Flask):
8030
```bash
8131
pip install Flask
8232
python3 Easy-File-Cleanup.py --html
8333
```
84-
Opens in your browser automatically. See [Web Interface Guide](docs/web.md) for details, features, and troubleshooting.
8534

86-
### Terminal Interface (TUI)
87-
For terminal users who like keyboard navigation and a full-screen text UI.
35+
**Terminal Interface**:
8836
```bash
89-
# Launch the TUI and start in your Downloads folder
9037
python3 Easy-File-Cleanup.py --tui ~/Downloads
9138
```
92-
This opens a full-screen terminal browser. See [TUI Guide](docs/tui.md) for keyboard shortcuts and navigation.
9339

94-
### Command Line (Automation)
95-
For scripts, cron jobs, and power users who want non-interactive runs.
40+
**Direct Organization**:
9641
```bash
97-
python3 Easy-File-Cleanup.py ~/Downloads --yes --quiet
42+
python3 Easy-File-Cleanup.py ~/Downloads
43+
```
44+
45+
## Installation
46+
47+
Only needed if using the command-line interface. Desktop apps bundle everything.
48+
49+
```bash
50+
git clone https://github.com/StewAlexander-com/File_Cleanup.git
51+
cd File_Cleanup
52+
chmod +x Easy-File-Cleanup.py
53+
pip install Flask # Only needed for --html flag
9854
```
99-
Fully automated, no prompts. See [Automation Guide](#automation--scripting) below or [example script](examples/automation.sh).
10055

101-
## Desktop Apps (PyInstaller)
56+
**Requirements**: Python 3.6+
57+
58+
## Desktop Apps
10259

103-
**Standalone apps with Python and Flask bundled — no installation required.**
60+
Standalone apps with Python and Flask bundled — no installation required. Double-click to launch the web UI.
10461

105-
Prefer double-click over the command line? Build or download a small desktop launcher for the web UI. The CLI/TUI stay exactly the same.
62+
### Download
10663

107-
- **Download ready-to-run apps (no Python needed)**:
108-
- macOS: [Mac-File-Cleanup.zip](https://github.com/StewAlexander-com/File_Cleanup/releases/download/v4.0/Mac-File-Cleanup.zip) (contains `Mac File Cleanup.app` — unzip first, then double-click the `.app`) — **Universal app (Intel + Apple Silicon)**
109-
- Windows: Pre-built `.exe` files are not available due to security restrictions. Please build from source (see [Building Windows Releases](#building-windows-releases) below) or use the CLI/TUI interfaces directly.
110-
- Source zip: [EasyFileCleanup-4.0-source.zip](https://github.com/StewAlexander-com/File_Cleanup/releases/download/v4.0/EasyFileCleanup-4.0-source.zip)
111-
- **First run (macOS)**: See [First Run Instructions (macOS)](#first-run-instructions-macos) below for step-by-step instructions.
112-
- **Run**: Double-click; the web UI opens on `http://127.0.0.1:<port>` and your default browser opens automatically.
113-
- **Dependencies**: Python and Flask are already bundled in the apps; CLI `--html` still needs `pip install Flask`.
114-
- **Security**: Localhost-only; the app never exposes your files over the network or internet.
115-
- **Build yourself (optional)**:
116-
- Requirements: Python 3.x, Flask (`pip install Flask`), PyInstaller (`pip install pyinstaller`) with support for `--target-arch universal2`
117-
- macOS: `./scripts/build_gui_mac.sh` (builds a **universal** app that runs on both Intel and Apple Silicon Macs)
118-
- Windows: See [Building Windows Releases](#building-windows-releases) below for detailed instructions
64+
- **macOS**: [Mac-File-Cleanup.zip](https://github.com/StewAlexander-com/File_Cleanup/releases/download/v4.0/Mac-File-Cleanup.zip) (Universal app for Intel + Apple Silicon)
65+
- **Windows**: Not available (build from source — see below)
66+
- **Source**: [EasyFileCleanup-4.0-source.zip](https://github.com/StewAlexander-com/File_Cleanup/releases/download/v4.0/EasyFileCleanup-4.0-source.zip)
11967

12068
### Building Windows Releases
12169

122-
**⚠️ Important**: Due to Windows 11 security restrictions and Sentinel One false positives, pre-built Windows executables are not provided. To create a Windows executable that avoids security violations, follow these steps:
70+
**⚠️ Important**: Due to Windows 11 security restrictions and Sentinel One false positives, pre-built Windows executables are not provided.
12371

12472
**Option 1: Build Locally (Recommended)**
12573

126-
1. **Install dependencies**:
74+
1. Install dependencies:
12775
```powershell
12876
pip install -r requirements.txt
12977
pip install pyinstaller
13078
```
13179

132-
2. **Build the executable**:
80+
2. Build the executable:
13381
```powershell
13482
powershell -ExecutionPolicy Bypass -File scripts/build_gui_windows.ps1
13583
```
13684

13785
3. **Code Signing (Strongly Recommended)**: To prevent Windows Defender and security software from flagging the executable:
13886
- Obtain a code signing certificate (Extended Validation recommended)
139-
- Sign the executable after building:
87+
- Sign the executable:
14088
```powershell
14189
signtool sign /f "path\to\certificate.pfx" /p "password" /t "http://timestamp.digicert.com" /fd sha256 "dist\Win-File-Cleanup.exe"
14290
```
143-
- See [Microsoft's Code Signing Guide](https://learn.microsoft.com/en-us/windows/win32/win_cert/sign) for detailed instructions
91+
- See [Microsoft's Code Signing Guide](https://learn.microsoft.com/en-us/windows/win32/win_cert/sign) for details
14492
145-
4. **Alternative: Use Python directly** (avoids all security issues):
93+
4. **Alternative**: Use Python directly to avoid all security issues:
14694
```powershell
14795
python Easy-File-Cleanup.py --html
14896
```
149-
Or use the TUI:
150-
```powershell
151-
python Easy-File-Cleanup.py --tui
152-
```
15397

15498
**Option 2: GitHub Actions Build**
15599

156-
1. Run the workflow: `gh workflow run build-windows.yml`
100+
1. Run: `gh workflow run build-windows.yml`
157101
2. Download the artifact from the Actions tab
158-
3. **Note**: You will still need to code sign the artifact to avoid security warnings
102+
3. **Note**: Code signing is still required to avoid security warnings
159103

160-
**Additional Resources**:
104+
**Resources**:
161105
- [PyInstaller Windows Guide](https://pyinstaller.org/en/stable/when-things-go-wrong.html#code-signing-on-windows)
162106
- [Microsoft Code Signing Documentation](https://learn.microsoft.com/en-us/windows/win32/win_cert/sign)
163107
- [Windows Defender False Positives](https://learn.microsoft.com/en-us/microsoft-365/security/intelligence/false-positives-negatives)
164108

165109
### First Run Instructions (macOS)
166110

167-
If you see a security warning when trying to open `Mac File Cleanup.app`, macOS is blocking the unsigned app.
111+
If you see a security warning when opening `Mac File Cleanup.app`, macOS is blocking the unsigned app.
168112

169-
**Quick summary**: Download and unzip the app, try to open it (you'll see a warning), then go to **System Settings → Privacy & Security** and click **"Open Anyway"** next to the blocked app message. Confirm in the popup, then you can run the app normally.
113+
**Quick fix**: Download and unzip the app, try to open it (you'll see a warning), then go to **System Settings → Privacy & Security** and click **"Open Anyway"** next to the blocked app message. Confirm in the popup.
170114

171-
\* **Note for Intel Mac users**: If the app won't open even after following the security steps, you may have an older build that only supports Apple Silicon. See the [macOS First Run Guide](docs/macos-first-run.md) for troubleshooting and build instructions.
115+
**Note for Intel Mac users**: If the app won't open after following security steps, you may have an older build. See the [macOS First Run Guide](docs/macos-first-run.md) for troubleshooting.
172116

173-
For detailed step-by-step instructions with screenshots and alternative methods, see the [macOS First Run Guide](docs/macos-first-run.md).
117+
For detailed step-by-step instructions with screenshots, see the [macOS First Run Guide](docs/macos-first-run.md).
174118

175-
## Features
119+
## Usage
176120

177-
### Core Functionality
178-
- Automatic file organization by extension
179-
- Duplicate handling (interactive or automatic) — prompts you to overwrite, create copies, or keep both versions
180-
- Verification of organization — checks moves and logs actions
181-
- Detailed logging
182-
- Cross-platform (Windows, macOS, Linux)
121+
### Command Line Options
183122

184-
### Interface Options
185-
- **Web UI**: Point-and-click interface with visual feedback, graphs, and directory tree ([see guide](docs/web.md))
186-
- **TUI**: Full-screen terminal browser with keyboard navigation ([see guide](docs/tui.md))
187-
- **CLI**: Direct command-line operation for automation
123+
| Flag | Description |
124+
|------|-------------|
125+
| `--html` | Launch web interface (requires Flask) |
126+
| `--tui` | Launch terminal interface |
127+
| `--yes` / `--non-interactive` | Auto-create copies for duplicates (recommended for scripts) |
128+
| `--overwrite` | Auto-overwrite duplicates (⚠️ use only if you're certain) |
129+
| `--quiet` | Minimal output (for automation and cron jobs) |
130+
| `--help` | Show full help |
131+
132+
### Examples
188133

189-
### Automation
190-
- Non-interactive flags for scripts and cron jobs
191-
- Consistent exit codes
192-
- Silent operation mode
193-
- Fast failure on errors
134+
```bash
135+
# Organize specific directory
136+
python3 Easy-File-Cleanup.py ~/Downloads
137+
138+
# Use partial path matching
139+
python3 Easy-File-Cleanup.py Downloads
140+
141+
# Organize current directory
142+
python3 Easy-File-Cleanup.py .
143+
144+
# Interactive mode (guided selection)
145+
python3 Easy-File-Cleanup.py
146+
147+
# Automated (no prompts)
148+
python3 Easy-File-Cleanup.py ~/Downloads --yes --quiet
149+
```
194150

195151
## How It Works
196152

@@ -202,8 +158,8 @@ For detailed step-by-step instructions with screenshots and alternative methods,
202158
6. Verifies organization
203159
7. Creates/updates `organization_log.txt`
204160

205-
**Example output structure**:
206-
```text
161+
**Example output**:
162+
```
207163
Downloads/
208164
├── pdf/
209165
│ ├── document1.pdf
@@ -215,41 +171,14 @@ Downloads/
215171
└── organization_log.txt
216172
```
217173

218-
## Usage
219-
220-
### Basic Command Line
221-
222-
```bash
223-
# Organize specific directory (full path)
224-
python3 Easy-File-Cleanup.py /Users/name/Downloads
225-
226-
# Use home shortcut
227-
python3 Easy-File-Cleanup.py ~/Downloads
228-
229-
# Use partial path matching (searches current directory and home)
230-
python3 Easy-File-Cleanup.py Downloads
231-
232-
# Organize the current directory
233-
python3 Easy-File-Cleanup.py .
234-
```
235-
236-
### Interactive Mode
237-
238-
Run without arguments for guided selection:
239-
```bash
240-
python3 Easy-File-Cleanup.py
241-
```
242-
243-
### Available Flags
174+
## Features
244175

245-
| Flag | Description |
246-
|------|-------------|
247-
| `--html` | Launch web interface (requires Flask) |
248-
| `--tui` | Launch terminal interface |
249-
| `--yes` / `--non-interactive` | Auto-create copies for duplicates (recommended for scripts) |
250-
| `--overwrite` | Auto-overwrite duplicates (⚠️ use only if you're certain) |
251-
| `--quiet` | Minimal output (for automation and cron jobs) |
252-
| `--help` | Show full help |
176+
- **Multiple Interfaces**: Web UI (point-and-click), TUI (keyboard navigation), CLI (automation)
177+
- **Duplicate Handling**: Interactive prompts or automatic copy creation
178+
- **Verification**: Checks moves and logs all actions
179+
- **Automation Ready**: Non-interactive flags, consistent exit codes, silent mode
180+
- **Detailed Logging**: Complete record of all file movements in `organization_log.txt`
181+
- **Cross-platform**: Windows, macOS, and Linux
253182

254183
## Automation & Scripting
255184

@@ -260,43 +189,40 @@ Fully automatable for cron jobs, CI/CD, and scripts.
260189
python3 Easy-File-Cleanup.py ~/Downloads --yes --quiet
261190
```
262191

263-
**Cron example** (Linux/macOS only):
192+
**Cron example** (Linux/macOS):
264193
```bash
265194
# Runs daily at 2 AM
266195
0 2 * * * /usr/bin/python3 /path/to/Easy-File-Cleanup.py ~/Downloads --yes --quiet
267196
```
268197

269-
**Exit codes** (suitable for CI/CD pipelines and monitoring tools):
198+
**Exit codes**:
270199
- `0`: Success
271200
- `1`: Error (invalid directory, organization failed)
272201
- `2`: Invalid arguments
273202
- `130`: Interrupted (Ctrl+C)
274203

275-
See [examples/automation.sh](examples/automation.sh) for a complete automation script example.
276-
277204
**Automation features**:
278205
- No interactive prompts with `--yes`/`--non-interactive`/`--overwrite`
279206
- Silent operation with `--quiet` (errors to stderr)
280207
- Fast failure on invalid inputs
281-
- Flag validation prevents conflicts: automation flags (`--yes`, `--non-interactive`, `--overwrite`, `--quiet`) cannot be combined with interactive flags (`--html`, `--tui`)
208+
- Flag validation prevents conflicts: automation flags cannot be combined with interactive flags (`--html`, `--tui`)
209+
210+
See [examples/automation.sh](examples/automation.sh) for a complete automation script example.
282211

283212
## Testing
284213

285-
Run the test suite:
286214
```bash
287215
python3 test_file_cleanup.py
288216
```
289217

290-
All tests run locally without network access — safe to run on any machine. ✅
218+
All tests run locally without network access. ✅
291219
**Test coverage**: 9 core tests + 18 web interface tests. All tests pass ✅
292220

293221
For detailed testing information, see [TEST_PLAN.md](TEST_PLAN.md).
294222

295223
## Documentation
296224

297-
**New users**: Start with the Web Interface Guide. Terminal users should check the TUI Guide.
298-
299-
**User Guides** (start here):
225+
**User Guides**:
300226
- [Web Interface Guide](docs/web.md) - Detailed web UI documentation, features, and troubleshooting
301227
- [TUI Guide](docs/tui.md) - Terminal interface navigation, keyboard shortcuts, and usage
302228
- [macOS First Run Guide](docs/macos-first-run.md) - Step-by-step instructions for allowing the Mac app to run

0 commit comments

Comments
 (0)