FileOrb v1.0 — Complete How-To-Use Guide

Author: Instagram @x404ctl | GitHub @MAliXCS | Alizarghunrajput@gmail.com

Part 1: Getting Started

Step 1 — Install Python

FileOrb requires Python 3.8 or newer. No pip packages needed.

Download Python from: https://www.python.org/downloads/

During installation on Windows, check "Add Python to PATH".

Verify your installation:

python --version

Step 2 — Run FileOrb

python fileorb_v1.0.py

On Windows you can also double-click the file if .py files are associated with Python.

The window opens to 1280×800 pixels and is freely resizable (minimum 1000×640).

Step 3 — Set Your Folders

Before doing anything else, go to the Settings tab and configure two folders:

Setting	What to put here
Watch Folder	The messy folder you want to clean up (e.g. `C:\Users\You\Downloads`)
Output Folder	Where organized files go (e.g. `C:\Users\You\Organized`)

Click Browse next to each field to pick them visually.

You can use the same folder for both (in-place organization), but a separate output folder is recommended for safety.

Part 2: Organizing Files

The Core Workflow

Set Watch Folder → Click Scan → Review table → Click Apply All

Scanning Files

Click Scan in the Organize tab toolbar.

FileOrb reads every file in your Watch Folder, classifies each one by extension, and loads them into the table. A progress bar animates while scanning. The table shows:

File Name — the original filename
Category — what type of file it is (Images, Code, Audio, Video, etc.)
Size — human-readable file size
Age — how recently the file was modified
Destination — the subfolder where FileOrb will put it
Confidence — how certain the classifier is (displayed as a bar)
Status — starts as Pending

If no Watch Folder is set, FileOrb loads 50 sample files so you can explore the interface first.

Understanding Destinations

FileOrb maps each file extension to a specific destination folder. For example:

File	Destination
`photo.jpg`	`Images/Photos`
`invoice.pdf`	`Documents/PDF`
`song.mp3`	`Audio/Music`
`project.blend`	`Blender/Projects`
`script.py`	`Code/Python`
`design.psd`	`Adobe/Photoshop`

These destinations are relative to your Output Folder. So if your Output Folder is C:\Organized, then photo.jpg goes to C:\Organized\Images\Photos\photo.jpg.

270+ file types are mapped. Unmapped files go to Other/Misc.

Filtering the Table

Use the filter buttons at the top of the toolbar to view only specific categories:

Click Images to see only image files
Click Code to see only source code files
Click All to return to the full list

Filtering doesn't affect which files get moved — it only changes what you see.

Approving and Skipping Files

You have full control over which files get moved:

To approve specific files:

Select them (click, Shift+click for range, Ctrl+click for individual, or Ctrl+A for all)
Click Approve (bottom bar or right-click menu)

To skip files (exclude from organizing):

Select them
Click Skip or press Delete

Status colours:

White row = Pending (will be moved on Apply All)
Green row = Approved
Orange row = Skipped (will not be moved)
Red tinted = Duplicate or suspicious

Changing a File's Destination

If you disagree with where FileOrb wants to put a file:

Select the file(s)
Right-click → Change Destination (or click Change Dest in the bottom bar)
Type the new destination folder path
Click Apply

The change applies to all selected files at once.

Applying / Moving Files

When you're ready to actually move files on disk, click Apply All.

A confirmation dialog shows:

How many files will be moved
Where they're going (or notes if no output folder is set)
Whether flat mode is active

Click Yes to proceed. Files move in a background thread — the progress bar and log update live.

If a file with the same name already exists in the destination, FileOrb renames the incoming file to filename_copy.ext automatically.

Flat Output Mode — All Files in One Folder

By default, FileOrb creates a folder hierarchy under your Output Folder:

Output/
  Images/Photos/
  Documents/PDF/
  Audio/Music/
  ...

If you want all files dumped into the Output Folder root with no subfolders:

Check "All files in one folder" in the bottom bar of the Organize tab
Or enable it in Settings → Folder Configuration

This is useful when you just want everything consolidated in one place without a hierarchy.

Adding Files Manually

To add specific files without scanning an entire folder:

Click Add Files in the toolbar
Browse and select one or more files (multi-select supported)
They appear in the table as Pending with auto-detected destinations

You can also use the drag-and-drop zone in the sidebar (click it to browse).

Undoing Actions

FileOrb keeps a 50-step undo history of every change made to the file list.

Action	Shortcut
Undo last change	Ctrl+Z
Redo	Ctrl+Y or Ctrl+Shift+Z
Undo all moves (restore to Pending)	Click "Undo All" button

Note: Undo restores the FileOrb list state, not actual file moves on disk. If files have already been physically moved, Undo All restores their status to Pending but does not move them back. Use your OS undo (Ctrl+Z in File Explorer on Windows) for that.

Part 3: Real-Time Folder Watching

The real-time watcher automatically detects new files dropped into your Watch Folder and adds them to the queue instantly.

Enabling the Watcher

Make sure a Watch Folder is set in Settings
Click the [RT] Watch: OFF button in the toolbar
The button turns green: [RT] Watch: ON

Now drop any file into your Watch Folder. Within 2 seconds it appears in the table with status Pending and note "auto-detected".

Disabling the Watcher

Click the green [RT] Watch: ON button again. It turns dark and stops.

Notes

The watcher only picks up files that appear after it was started
Deleted files are not removed from the queue automatically
The watcher runs in a background thread and does not freeze the UI

Part 4: Custom Sorting Rules

The Rules tab lets you define your own file patterns beyond the built-in extension map.

Creating a Rule

Click Add in the Rules tab toolbar
Enter a Pattern — glob-style, comma-separated:
- *.jpg, *.png — all JPG and PNG files
- invoice_* — any file starting with "invoice_"
- *.docx — all Word documents
Enter a Destination folder:
- Documents/Finance
- Work/Invoices
Make sure Enabled is checked
Click Save

Rule Priority

Rules are matched top to bottom. If two rules match the same file, the one higher in the list wins. Put specific rules (like invoice_*) above general ones (like *.pdf).

Toggling Rules

Double-click any rule row to toggle it on or off instantly without deleting it. Useful for temporarily disabling a rule.

Part 5: File Intelligence

The Intelligence tab turns FileOrb into a lightweight file forensics tool.

Opening a File for Analysis

Method 1: Click Browse File in the Intelligence tab and select any file.

Method 2: In the Organize tab, right-click any file with a real path → Analyse in Intelligence.

Analysis runs in a background thread. Results populate all sub-tabs simultaneously.

Reading the Metadata Table

The Metadata & Properties sub-tab shows every piece of information extractable from the file:

Size (bytes) and human-readable equivalent
Created / Modified / Accessed timestamps
Is Symlink — if True, this is a pointer, not a real file
Permissions — Unix-style octal permission code
Hidden — whether the filename starts with a dot
Extension — the declared extension
Detected Type — what the magic bytes say the file actually is
MIME (magic) — detected MIME type
TYPE MISMATCH — appears only when extension and magic disagree (this is a red flag)

Double-click any row to copy its value to the clipboard.

Reading the Entropy Graph

Each vertical bar represents a 4KB block of the file.

Blue = low entropy (plain text, structured data)
Orange = medium entropy (typical compiled code, mixed content)
Red = high entropy — above the 7.2 threshold line

When high entropy is normal: ZIP, RAR, 7Z, GZ, MP3, MP4, FLAC — compressed and encoded formats naturally have high entropy.

When high entropy is suspicious: A .docx, .exe, .py, .txt, or .jpg file with entropy above 7.2 may be packed, encrypted, or contain hidden data. This is a common indicator in malware that uses compression to evade signature detection.

Reading EXIF Data

For JPEG photos, FileOrb extracts the embedded EXIF block using a pure-Python parser. No external libraries.

Key fields to look for:

Field	What it reveals
Make / Model	Camera or phone brand and model
DateTimeOriginal	Exact date and time the photo was taken
GPSInfoIFDPointer	GPS coordinates were embedded (location data)
Software	What software last processed or saved the image
Artist	Who the image was attributed to in metadata
ISOSpeedRatings	Camera sensitivity setting
FocalLength	Lens focal length used

If GPS Block: Present appears in the EXIF results, the photo contains location coordinates. This is a significant privacy concern for photos shared online.

Reading the Security Report

The Security Flags sub-tab shows a formatted report. Key sections:

Threat Level:

CLEAN — no suspicious indicators
MEDIUM — minor flags (hidden file, symlink, etc.)
HIGH — high-entropy non-archive, suspicious extension, or type mismatch

Suspicious Flags: Each flag is listed with a description. Common flags:

Suspicious extension: .exe — file uses an extension that can execute code
High entropy in non-archive file — possible packing or encryption
Double extension: .pdf.exe — classic filename masking trick
Is a symbolic link — pointer that could redirect to a dangerous location
Hidden file (dot-prefix) — file is hidden from normal directory listings

Reading the Hex Dump

The Structure / Hex Preview sub-tab shows the first 512 bytes in hex and ASCII side by side.

How to read file signatures from the hex dump:

First bytes	File type
`25 50 44 46` (`%PDF`)	PDF document
`89 50 4E 47` (`PNG`)	PNG image
`FF D8 FF`	JPEG image
`4D 5A` (`MZ`)	Windows executable (.exe, .dll)
`50 4B 03 04` (`PK`)	ZIP archive (also .docx, .xlsx, .jar)
`52 61 72 21` (`Rar!`)	RAR archive
`7F 45 4C 46` (`.ELF`)	Linux executable
`1F 8B`	GZip archive
`53 51 4C 69 74 65` (`SQLite`)	SQLite database

If the first bytes don't match the extension, the file has been renamed or tampered with.

Part 6: VirusTotal Lookup

Setup

Go to https://www.virustotal.com and create a free account
Click your profile icon → API Key
Copy the key
In FileOrb → Settings → VirusTotal API Key → paste it
Click Show to verify it was pasted correctly

Running a Lookup

Open the Intelligence tab
Analyse any file (Browse File or right-click from Organize tab)
Wait for the SHA256 hash to appear in the right panel
Click VT Lookup

Results appear in the Threat Summary panel:

0/72 detections = clean according to 72 antivirus engines
3/72 detections = flagged by 3 engines (medium concern)
45/72 detections = almost certainly malware

The Security Flags report is also updated with the engine names that flagged the file.

Free API Limits

The free VirusTotal API allows:

4 lookups per minute
500 lookups per day
No file uploads — only hash queries

Part 7: Clipboard Operations

FileOrb supports full clipboard copy/cut/paste for file rows in the Organize table.

Copying Rows

Select one or more rows and press Ctrl+C.

FileOrb copies them as tab-separated text:

Name    Category    Size    Age    Destination    Status
photo.jpg    Images    3.2 MB    2h ago    Images/Photos    Pending
song.mp3    Audio    8.7 MB    1d ago    Audio/Music    Pending

You can paste this into Excel, Notepad, or any other app.

Cutting Rows

Ctrl+X copies the rows AND removes them from the list. This is undoable with Ctrl+Z.

Pasting Rows

Ctrl+V reads TSV rows from the clipboard and adds them back to the list. Duplicate rows (same name + destination) are silently skipped.

Part 8: Log System

The Live Logs tab records every action FileOrb takes.

Filtering Logs

Search box — type any text to filter in real time
Level buttons — show only INFO, SUCCESS, WARNING, or ERROR entries
ALL — show everything

Exporting Logs

Click Export → choose a save location → a .txt file is saved with all entries.

Format:

[2025-01-15 14:32:07.123] [SUCCESS] Moved: invoice.pdf  ->  Documents/PDF
[2025-01-15 14:32:07.456] [WARNING] Skipped: readme.txt

Copying Log Lines

Double-click any line in the log terminal to copy it to the clipboard.

Part 9: Analytics Dashboard

The Analytics tab shows statistics about the current file queue.

Files by Category — count of files per detected category
Status Overview — breakdown of Pending / Approved / Moved / Skipped with percentage bars
Top Extensions — the 15 most frequent file extensions in the queue with colour-coded bars

Click Refresh after any changes to update the charts.

Part 10: Keyboard Shortcuts Reference

Shortcut	What it does
Ctrl+A	Select all visible rows in the file table
Ctrl+C	Copy selected rows to clipboard as TSV
Ctrl+X	Cut selected rows (remove + copy)
Ctrl+V	Paste rows from clipboard into table
Ctrl+Z	Undo last action (50-step history)
Ctrl+Y	Redo
Ctrl+Shift+Z	Redo (alternative)
Delete	Skip selected files
Double-click (table)	Open file detail popup
Double-click (rules)	Toggle rule on/off
Double-click (metadata)	Copy value to clipboard
Double-click (log line)	Copy log line to clipboard
Right-click (table)	Open context menu
Scroll Wheel	Scroll any table or panel vertically
Shift+Scroll	Scroll horizontally

Tips and Best Practices

Always do a dry run first. Click Scan, review the table, check destinations — then Apply All. Never skip the preview step on important folders.

Use the flat folder option for quick cleanups. If you just want to consolidate a Downloads folder without a hierarchy, enable "All files in one folder" before applying.

Check entropy on unfamiliar executables. Before running an .exe from an unknown source, drop it into the Intelligence tab. High entropy + suspicious VT results = don't run it.

Strip EXIF before sharing photos. Open photos in Intelligence → check the EXIF tab. If GPS coordinates are present, consider using an EXIF-stripping tool before posting online.

Use rules for recurring patterns. If you always want files named invoice_* to go to Documents/Finance, create a rule once and it works forever.

Export logs after large operations. After organizing thousands of files, export the log immediately so you have a record of every move in case you need to trace a file.

FileOrb v1.0 — Made by Muhammad Ali Instagram @x404ctl | GitHub @MAliXCS | Alizarghunrajput@gmail.com

FilesExpand file tree

HOW_TO_USE.md

Latest commit

History