organize-tool Documentation

An organize configuration file can be written in YAML or JSON. The top-level element must be a dictionary containing a rules key, which holds a list of rule objects. Each rule object must include locations and actions keys.

Rules are processed in order: from top to bottom for rules, then top to bottom for locations, then top to bottom for filters, and finally top to bottom for actions.

rules:
  - locations: "~/Desktop"
    actions:
      - echo: "Hello World!"

You can categorize rules in your YAML configuration using tags. Use the --tags and --skip-tags CLI options to include or exclude specific groups of rules. These options accept a comma-separated list of tags.

Rule Configuration Example:

rules:
  - name: My first rule
    actions:
      - echo: "Hello world"
    tags:
      - debug
      - fast

CLI Usage:

organize sim --tags=debug,foo --skip-tags=slow

Special Tags:

• always: Rules with this tag will always run unless --skip-tags=always is used.
• never: Rules with this tag will never run unless --tags=never is used.

Locations can be defined as relative paths (e.g., locations: "docs"), which are relative to the current working directory. You can control the base directory for these relative paths using the --working-dir CLI flag when running the sim command.

# huge-pic-warner.yaml
rules:
  - locations: "docs" # relative to working dir
    filters:
      - extension: jpg
      - size: ">3 MB"
    actions:
      - echo: "Warning - huge pic found!"

organize sim huge-pic-warner.yaml --working-dir=some/other/dir/

Before running your rules, you can check your configuration for errors using the check command. Use the --debug flag to see detailed debug output during the validation process.

organize check
organize check --debug

You can inject environment variables into location paths using two syntaxes. When using the {env} syntax, ensure the path is enclosed in quotes.

• {env.VARIABLE_NAME}
• $VARIABLE_NAME

rules:
  - locations:
      # via {env} - quotes are required
      - "{env.MY_FOLDER}"

      # via $
      - "$MY_FOLDER"

      # combined with options
      - path: "{env.OTHER_FOLDER}/Inbox/Invoices"
        max_depth: null
    actions:
      - echo: "{path}"

Use the show command to find where your configuration file is located. Use the --path flag to see the absolute path to the default configuration file.

organize show             # opens the folder containing the config
organize show --path       # shows the full path to the default config

When running the container, ensure you mount your data directory and your configuration file correctly.

Warning: Since organize moves files, if you move a file to a directory that is not persisted via a volume mount, the file will be lost when the container stops.

To run a basic setup, mount your local configuration file to /config/config.yml and your data directory to /data inside the container.

docker run -v ./docker-conf.yml:/config/config.yml -v .:/data organize run

To build the Docker image, navigate to the directory containing the Dockerfile and run the docker build command. The resulting image will be tagged as organize.

docker build -t organize .

By default, rules target files. To target folders instead, set targets: "dirs".

When targeting directories, filters adjust their behavior automatically. For example, the size filter will return the sum of the sizes of all files within the folder. Note that some filters (like exif or filecontent) are file-specific and will return an error if applied to a directory.

rules:
  - locations: ~/Desktop
    targets: dirs
    actions: ...

Use run to execute the rules defined in your configuration, or sim to simulate them (dry run). You can specify a specific configuration file and a working directory.

# Run/simulate default config
organize sim
organize run

# Run/simulate a specific config file
organize sim [FILE]
organize run [FILE]

# Run/simulate a specific config file in a specific directory
organize sim [FILE] --working-dir=~/Documents