---
organize - The file management automation tool
Full documentation at Read the docs
## v3 is now available
The new version should be *much* faster and fix a lot of bugs. It also comes with
a some new actions, filters and options.
If you encounter any other bugs or problems during the migration, please reach out!
- [See the changelog](https://tfeldmann.github.io/organize/changelog/)
- [Migration guide](https://tfeldmann.github.io/organize/migrating/#migrating-from-v2-to-v3)
## About
Your desktop is a mess? You cannot find anything in your downloads and
documents? Sorting and renaming all these files by hand is too tedious?
Time to automate it once and benefit from it forever.
**organize** is a command line, open-source alternative to apps like Hazel (macOS)
or File Juggler (Windows).
### People use this for:
- Sorting and tagging pictures into various folder structures based on EXIF data
- Sorting and renaming PDF invoices based on file content
- Removing incomplete downloads from their ~/Downloads
- Cleaning up their ~/Desktop from unused files
- Freeing up disk space by removing duplicates
- Automating various business processes
- and many more
## Features
Some highlights include:
- Safe moving, renaming, copying of files and folders with conflict resolution options.
- Fast duplicate file detection.
- Exif tags extraction.
- Categorization via text extracted from PDF, DOCX and many more.
- Powerful template engine.
- Inline python and shell commands as filters and actions for maximum flexibility.
- Everything can be simulated before touching your files.
- Works on macOS, Windows and Linux.
- Free and open source software.
## Getting started
### Installation
Only python 3.9+ is needed.
Install it via your package manager or from [python.org](https://python.org).
Installation is done via pip. Note that the package name is `organize-tool`:
```bash
pip install -U organize-tool
```
This command can also be used to update to the newest version. Now you can run `organize --help` to check if the installation was successful.
### Create your first rule
In your shell, run `organize new` and then `organize edit` to edit the configuration:
```yaml
rules:
- name: "Find PDFs"
locations:
- ~/Downloads
subfolders: true
filters:
- extension: pdf
actions:
- echo: "Found PDF!"
```
> If you have problems editing the configuration you can run `organize show --reveal` to reveal the configuration folder in your file manager. You can then edit the `config.yaml` in your favourite editor.
save your config file and run:
```sh
organize run
```
You will see a list of all `.pdf` files you have in your downloads folder (+ subfolders).
For now we only show the text `Found PDF!` for each file, but this will change soon...
(If it shows `Nothing to do` you simply don't have any pdfs in your downloads folder).
Run `organize edit` again and add a `move`-action to your rule:
```yml
actions:
- echo: "Found PDF!"
- move: ~/Documents/PDFs/
```
Now run `organize sim` to see what would happen without touching your files.
You will see that your pdf-files would be moved over to your `Documents/PDFs` folder.
Congratulations, you just automated your first task. You can now run `organize run`
whenever you like and all your pdfs are a bit more organized. It's that easy.
> There is so much more. You want to rename / copy files, run custom shell- or python scripts, match names with regular expressions or use placeholder variables? organize has you covered. Have a look at the advanced usage example below!
## Example rules
Here are some examples of simple organization and cleanup rules. Modify to your needs!
Move all invoices, orders or purchase documents into your documents folder:
```yaml
rules:
- name: "Sort my invoices and receipts"
locations: ~/Downloads
subfolders: true
filters:
- extension: pdf
- name:
contains:
- Invoice
- Order
- Purchase
case_sensitive: false
actions:
- move: ~/Documents/Shopping/
```
Recursively delete all empty directories:
```yaml
rules:
- name: "Recursively delete all empty directories"
locations:
- path: ~/Downloads
targets: dirs
subfolders: true
filters:
- empty
actions:
- delete
```
You'll find many more examples in the full documentation.
## Command line interface
```txt
organize - The file management automation tool.
Usage:
organize run [options] []
organize sim [options] []
organize new []
organize edit []
organize check []
organize debug []
organize show [--path|--reveal] []
organize list
organize docs
organize --version
organize --help
Commands:
run Organize your files.
sim Simulate organizing your files.
new Creates a new config.
edit Edit the config file with $EDITOR.
check Check whether the config file is valid.
debug Shows the raw config parsing steps.
show Print the config to stdout.
Use --reveal to reveal the file in your file manager
Use --path to show the path to the file
list Lists config files found in the default locations.
docs Open the documentation.
Options:
A config name or path to a config file
-W --working-dir The working directory
-F --format (default|jsonl) The output format [Default: default]
-T --tags Tags to run (eg. "initial,release")
-S --skip-tags Tags to skip
-h --help Show this help page.
```
## Other donation options:
ETH:
```
0x8924a060CD533699E230C5694EC95b26BC4168E7
```
BTC:
```
39vpniiZk8qqGB2xEqcDjtWxngFCCdWGjY
```
