Configuration

Editing the configuration

All configuration takes place in your config.yaml file.

  • To edit your configuration in $EDITOR run:

    $ organize config  # example: "EDITOR=vim organize config"
    
  • To show the full path to your configuration file:

    $ organize config --path
    
  • To open the folder containing the configuration file:

    $ organize config --open-folder
    
  • To debug your configuration run:

    $ organize config --debug
    

Environment variables

  • $EDITOR - The editor used to edit the config file.
  • $ORGANIZE_CONFIG - The config file path. Is overridden by --config-file cmd line argument.

Rule syntax

The rule configuration is done in YAML. You need a top-level element rules which contains a list of rules. Each rule defines folders, filters (optional) and actions.

config.yaml
rules:
  - folders:
      - ~/Desktop
      - /some/folder/
    filters:
      - lastmodified:
          days: 40
          mode: newer
      - extension: pdf
    actions:
      - move: ~/Desktop/Target/
      - trash

  - folders:
      - ~/Inbox
    filters:
      - extension: pdf
    actions:
      - move: ~/otherinbox
    # optional settings:
    enabled: true
    subfolders: true
    system_files: false
  • folders is a list of folders you want to organize.
  • filters is a list of filters to apply to the files - you can filter by file extension, last modified date, regular expressions and many more. See Filters.
  • actions is a list of actions to apply to the filtered files. You can put them into the trash, move them into another folder and many more. See Actions.

Other optional per rule settings:

  • enabled can be used to temporarily disable single rules. Default = true
  • subfolders specifies whether subfolders should be included in the search. Default = false. This setting only applies to folders without glob wildcards.
  • system_files specifies whether to include system files (desktop.ini, thumbs.db, .DS_Store) in the search. Default = false

Folder syntax

Every rule in your configuration file needs to know the folders it applies to. The easiest way is to define the rules like this:

config.yaml
rules:
  - folders:
      - /path/one
      - /path/two
    filters: ...
    actions: ...

  - folders:
      - /path/one
      - /another/path
    filters: ...
    actions: ...

Globstrings

You can use globstrings in the folder lists. For example to get all files with filenames ending with _ui and any file extension you can use:

config.yaml
rules:
  - folders:
      - '~/Downloads/*_ui.*'
    actions:
      - echo: '{path}'

You can use globstrings to recurse through subdirectories (alternatively you can use the subfolders: true setting as shown below)

config.yaml
rules:
  - folders:
      - '~/Downloads/**/*.*'
    actions:
      - echo: 'base {basedir}, path {path}, relative: {relative_path}'

  # alternative syntax
  - folders:
      - ~/Downloads
    subfolders: true
    actions:
      - echo: 'base {basedir}, path {path}, relative: {relative_path}'

The following example recurses through all subdirectories in your downloads folder and finds files with ending in .c and .h.

config.yaml
rules:
  - folders:
      - '~/Downloads/**/*.[c|h]'
    actions:
      - echo: '{path}'

Note

  • You have to target files with the globstring, not folders. So to scan through all folders starting with log_ you would write yourpath/log_*/*

Excluding files and folders

Files and folders can be excluded by prepending an exclamation mark. The following example selects all files in ~/Downloads and its subfolders - excluding the folder Software:

config.yaml
rules:
  - folders:
      - '~/Downloads/**/*'
      - '! ~/Downloads/Software'
    actions:
      - echo: '{path}'

Globstrings can be used to exclude only specific files / folders. This example:

  • adds all files in ~/Downloads
  • exludes files from that list whose name contains the word system ending in .bak
  • adds all files from ~/Documents
  • excludes the file ~/Documents/important.txt.
config.yaml
rules:
  - folders:
      - '~/Downloads/**/*'
      - '! ~/Downloads/**/*system*.bak'
      - '~/Documents'
      - '! ~/Documents/important.txt'
    actions:
      - echo: '{path}'

Note

  • Files and folders are included and excluded in the order you specify them!
  • Please make sure your are putting the exclamation mark within quotation marks.

Aliases

Instead of repeating the same folders in each and every rule you can use an alias for multiple folders which you can then reference in each rule. Aliases are a standard feature of the YAML syntax.

config.yaml
all_my_messy_folders: &all
  - ~/Desktop
  - ~/Downloads
  - ~/Documents
  - ~/Dropbox

rules:
  - folders: *all
    filters: ...
    actions: ...

  - folders: *all
    filters: ...
    actions: ...

You can even use multiple folder lists:

config.yaml
private_folders: &private
  - '/path/private'
  - '~/path/private'

work_folders: &work
  - '/path/work'
  - '~/My work folder'

all_folders: &all
  - *private
  - *work

rules:
  - folders: *private
    filters: ...
    actions: ...

  - folders: *work
    filters: ...
    actions: ...

  - folders: *all
    filters: ...
    actions: ...

  # same as *all
  - folders:
      - *work
      - *private
    filters: ...
    actions: ...

Filter syntax

filters is a list of Filters. Filters are defined like this:

config.yaml
rules:
  - folders: ...
    actions: ...
    filters:
      # filter without parameters
      - FilterName

      # filter with a single parameter
      - FilterName: parameter

      # filter expecting a list as parameter
      - FilterName:
        - first
        - second
        - third

      # filter with multiple parameters
      - FilterName:
          parameter1: true
          option2: 10.51
          third_argument: test string

Note

Every filter comes with multiple usage examples which should be easy to adapt for your use case!

Action syntax

actions is a list of Actions. Actions can be defined like this:

config.yaml
rules:
  - folders: ...
    actions:
      # action without parameters
      - ActionName

      # action with a single parameter
      - ActionName: parameter

      # filter with multiple parameters
      - ActionName:
          parameter1: true
          option2: 10.51
          third_argument: test string

Note

Every action comes with multiple usage examples which should be easy to adapt for your use case!

Variable substitution (placeholders)

You can use placeholder variables in your actions.

Placeholder variables are used with curly braces {var}. You always have access to the variables {path}, {basedir} and {relative_path}:

  • {path} – is the full path to the current file
  • {basedir} – the current base folder (the base folder is the folder you specify in your configuration).
  • {relative_path} – the relative path from {basedir} to {path}

Use the dot notation to access properties of {path}, {basedir} and {relative_path}:

  • {path} – the full path to the current file
  • {path.name} – the full filename including extension
  • {path.stem} – just the file name without extension
  • {path.suffix} – the file extension
  • {path.parent} – the parent folder of the current file
  • {path.parent.parent} – parent calls are chainable…
  • {basedir} – the full path to the current base folder
  • {basedir.parent} – the full path to the base folder’s parent

and any other property of the python pathlib.Path (official documentation) object.

Additionally Filters may emit placeholder variables when applied to a path. Check the documentation and examples of the filter to see available placeholder variables and usage examples.

Some examples include:

  • {lastmodified.year} – the year the file was last modified
  • {regex.yournamedgroup} – anything you can extract via regular expressions
  • {extension.upper} – the file extension in uppercase
  • … and many more.