Locations#

Locations are the folders in which organize searches for resources. You can set multiple locations for each rule if you want.

A minimum location definition is just a path where to look for files / folders:

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

If you want to handle multiple locations in a rule, create a list:

rules:
  - locations:
      - ~/Desktop
      - /usr/bin/
      - "%PROGRAMDATA%/test"
    actions: ...

Using options:

rules:
  - name: "Location list"
    locations:
      - path: "~/Desktop"
        max_depth: 3
    actions: ...

Location options#

rules:
  - locations:
      - path: ...
        min_depth: ...
        max_depth: ...
        search: ...
        exclude_files: ...
        exclude_dirs: ...
        system_exclude_files: ...
        system_exclude_dirs: ...
        ignore_errors: ...
        filter: ...
        filter_dirs: ...

path (str)
Path to a local folder

min_depth (int or null)
Minimum directory depth to search. This can be useful if you want to only handle files in subdirectories of location.

max_depth (int or null)
Maximum directory depth to search.

search ("breadth" or "depth")
Whether to use breadth or depth search to recurse into subfolders. Note that if you want to move or delete files from this location, this has to be set to "depth". (Default: "depth")

exclude_files (List[str])
A list of filename patterns that should be excluded in this location, e.g. ["~*"].

exclude_dirs (List[str])
A list of folder name patterns that will be used to filter out directory names in this location. e.g. ["do-not-move", "*-Important", "Backup*"]

system_exclude_files (List[str])
The list of filename patterns that are excluded by default. Defaults to: ["thumbs.db", "desktop.ini", "~$*", ".DS_Store", ".localized"]. Override with [] to include system files.

system_exclude_dirs (List[str])
The list of folder name patterns that are excluded by default (['.git', '.svn']). Override with [] to include system dirs.

ignore_errors (bool)
If true, any errors reading the location will be ignored.

filter (List[str])
A list of filename patterns that should be used in this location, e.g. ["*.py"]. All other files are skipped.

filter_dirs (List[str])
A list of patterns to match directory names that are included in this location. All other directories are skipped.

max_depth and subfolders#

• If subfolders: true is specified on the rule, all locations are set to max_depth: null by default.
• A max_depth setting in a location is given precedence over the rule's subfolders setting.

Environment variables in locations#

You can use environment variables in your locations. You can access them via the {env} placeholder or prefix them with a dollar sign.

Examples:

rules:
  - locations:
      # via {env} - the "" are important here!
      - "{env.MY_FOLDER}"

      # via $ - equal to the one above.
      - "$MY_FOLDER"

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

Relative locations#

Locations can be relative. This allows you to create simple one-off rules that can be copied between projects.

There is a command line option to change the working directory should you need it.

huge-pic-warner.yaml:

rules:
  - locations: "docs" # here "docs" is relative to the current working dir
    filters:
      - extension: jpg
      - size: ">3 MB"
    actions:
      - echo: "Warning - huge pic found!"

Then run it with:

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