#sanenames

sanenames is a small utility to help you keep directory and filenames sane.

By default, sanenames will replace whitespace characters with an underscore. Additionally, sanenames will warn you about files whose names contain characters which, if unescaped, carry meanings in various shells (e.g. | or *). You can adapt the default sanenames behavior to your needs via a configuration file.

Ideally, sanenames should make system administration easier by ensuring that filenames do not contain non-ASCII or shell expanded characters.

#Features

• small
• easily customizable
• platform independent

#Installation

Run

pip install sanenames

to install the latest version of sanenames from the Python Package Index.

#Usage

To rename files in a directory, simply run

sanenames path/to/directory

If you don't specify the path/to/directory explicitly, sanenames will default to the current working directory.

Please use sanenames with caution! Renaming files can break your system!

#Options

If you want to test the effects of the sanenames call without making the namechanges, add the -d (dry-run) flag to the command to see which renames sanenames would make if run properly.

Additional flags to the sanenames call allow

• file overwrites [-o],
• recursion through directories [-R],
• a more verbose output [-v], and
• not ignoring hidden files [-a].

For more details, run sanenames -h.

#Customization

You can customize sanenames to your desired behavior via config files.

The most straightforward way to change the sanenames behavior is to pass the path to a config file to the sanenames call with the --config-path argument. Alternatively, you can create a global configuration file at the location indicated by

sanenames --show-global-config-path

which will only be used if sanenames is called without the --config-path argument. If no global configuration file is found nor the --config-path argument is passed, sanenames will apply its default behavior.

In any case, the settings in the config files should only ever contain the differences to the sanenames standard behavior: I.e. there is no need to specify in every config file that whitespaces should be replaced with underscores. You can, of course, specify to replace whitespaces with dashes if you so like.

Every configuration file has to

• be written in the toml format, and
• can contain any combination of the [replacements] and [warning_chars] sections, whereby the replacements section has to contain key-value pairs, while the warning_chars section must be an array.

An example configuration which - in addition to the default sanenames behavior - also replaces German special characters with their ASCII equivalent would therefore look like this:

[replacements]
"ß" = "ss"
"ä" = "ae"
"ö" = "oe"
"ü" = "ue"
"Ä" = "Ae"
"Ö" = "Oe"
"Ü" = "Ue"

#Contribute

You're very welcome to contribute to this project!

#Issues

If you encounter a problem, suspect a bug, or would like to see an additional feature included in sanenames, please write to this mailing list. Once the issue has been sufficiently narrowed down, we will create a workable ticket here.

#Patches

If you have patches ready, please send them to this mailing list. Please adhere to the Conventional Commits specification in your patches and make sure the project stays REUSE compliant.

If you set up a local development version of the sanenames project with the following commands, you will automatically adhere to these requirements:

# clone the repository:
git clone https://git.sr.ht/~puer-robustus/sanenames
# create a python virtualenv for the project:
cd sanenames
python3 -m venv venv
# install the (development) dependencies into the virtualenv:
source venv/bin/activate
pip install -e .[dev]
# install the pre-commit hooks:
pre-commit install-hooks

# from now on, whenever you make some changes to your copy of
# the sanenames project, activate the virtualenv, and use
cz c
# to make commits

#License

Copyright (C) 2022 Alex alex@puer-robustus.eu

This work is licensed under multiple licenses.

• All original source code is licensed under MIT.
• Some configuration and data files are licensed under CC0-1.0.

For more accurate information, check the individual files.