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
.
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 = truesubfolders
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:
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:
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)
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
.
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
:
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
.
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.
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:
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:
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:
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.