dschlueter
2ec4d12d6c
- Add -s/--sequence option to select transformation sequences - Add -L flag to list all available sequences - Implement 5 hardcoded sequences: default, lower, upper, minimal, utf-8 - Refactor clean_filename() to support sequence-based transformations - Update all tests to pass sequence parameter (25 tests passing) - Add 8 new integration tests for sequence functionality - Update documentation (README, CHANGELOG, manpage) - Update shell completions (bash, zsh, fish) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
387 lines
14 KiB
Markdown
387 lines
14 KiB
Markdown
# NameToUnix
|
|
|
|
[](https://github.com/jamulix/NameToUnix/actions)
|
|
[](https://github.com/jamulix/NameToUnix/releases)
|
|
[](https://github.com/jamulix/NameToUnix/releases)
|
|
[](https://opensource.org/licenses/MIT)
|
|
|
|
**Filename Repair Tool for Linux** · Binary: `ntu`
|
|
|
|
(german and english)
|
|
|
|
A powerful command line tool for cleaning up file names according to Linux conventions.
|
|
It works under Linux. The program is useful if many file names, e.g. after downloading and unpacking zip files from Windows file systems
|
|
contain spaces or special characters. It saves an enormous amount of time by automatically replacing the offending characters.
|
|
|
|
I have been using a similar program - a Perl script - for about 15 years. It has saved me many, many hours of mindless renaming work. Now I'm learning Rust and wanted to write a useful command line application. ***NameToUnix*** is the result.
|
|
|
|
This is my first program in Rust. (Please have mercy on me.)
|
|
|
|
Ein leistungsstarkes Kommandozeilen-Tool zum Bereinigen von Dateinamen gemäß Linux-Konventionen.
|
|
Es funktioniert unter Linux. Das Programm ist sinnvoll, wenn viele Dateinamen z. B. nach einem Download und Entpacken von Zip-Dateien aus Windows-Dateisystemen
|
|
Leerzeichen oder Sonderzeichen enthalten. Es erspart enorm viel Zeit durch automatisches Ersetzen der störenden Zeichen.
|
|
|
|
Ich benutze ein ähnliches Programm - ein Perl-Skript - seit ca. 15 Jahren. Es hat mir schon viele, viele Stunden stumpfsinniger Umbenennungs-Arbeit erspart. Nun bin ich dabei, Rust zu lernen und wollte eine sinnvolle Kommandozeilenanwendung schreiben. ***NameToUnix*** ist dabei herausgekommen.
|
|
|
|
Dies ist mein erstes Programm in Rust. (Bitte seid gnädig.)
|
|
|
|
(c) 2025 Dieter Schlüter <dieter.schlueter@linix.de>
|
|
|
|
## ⚠️ BREAKING CHANGE in v1.0.0
|
|
|
|
**Recursion is now opt-in**: As of version 1.0.0, `ntu` processes only the
|
|
specified paths and their immediate children by default. Use the `-r` or
|
|
`--recursive` flag to enable recursive directory traversal.
|
|
|
|
**Migration**: Add `-r` to your existing commands:
|
|
```bash
|
|
# Old (v0.x): ntu /path/to/files
|
|
# New (v1.x): ntu -r /path/to/files
|
|
```
|
|
|
|
## Sequences
|
|
|
|
Starting with v1.1.0, `ntu` supports transformation sequences similar to detox. Sequences control how filenames are transformed:
|
|
|
|
- **default**: Standard transformation (umlauts→ASCII, spaces→underscores, remove special chars)
|
|
- **lower**: Like default, but convert to lowercase
|
|
- **upper**: Like default, but convert to UPPERCASE
|
|
- **minimal**: Only replace spaces, keep UTF-8 characters
|
|
- **utf-8**: UTF-8 friendly (keep umlauts, replace spaces, remove special chars)
|
|
|
|
```bash
|
|
# Use specific sequence
|
|
ntu -s lower /path/to/files
|
|
|
|
# List all available sequences
|
|
ntu -L
|
|
|
|
# List sequences with details
|
|
ntu -L -v
|
|
```
|
|
|
|
## Functions / Funktionen
|
|
|
|
- Replaces spaces and special characters in file and directory names with underscores
|
|
- Converts German umlauts to their ASCII counterparts (ä → ae, etc.)
|
|
- Supports recursive processing of directories
|
|
- Provides preview mode without actual changes
|
|
- Allows user-defined replacement rules via configuration file
|
|
- Supports exclusion patterns for specific file patterns/directory patterns
|
|
|
|
---
|
|
|
|
- Ersetzt Leerzeichen und Sonderzeichen in Datei- und Verzeichnisnamen durch Unterstriche
|
|
- Konvertiert deutsche Umlaute in ihre ASCII-Pendants (ä → ae, usw.)
|
|
- Unterstützt rekursive Verarbeitung von Verzeichnissen
|
|
- Bietet Vorschau-Modus ohne tatsächliche Änderungen
|
|
- Ermöglicht benutzerdefinierte Ersetzungsregeln über Konfigurationsdatei
|
|
- Unterstützt Ausschlussmuster für bestimmte Datei-Muster/Verzeichnis-Muster
|
|
|
|
## Installation
|
|
|
|
### Option 1: Pre-built Binary (Recommended)
|
|
|
|
Download the latest release for your platform from [GitHub Releases](https://github.com/jamulix/NameToUnix/releases):
|
|
|
|
```bash
|
|
# Linux x86_64
|
|
wget https://github.com/jamulix/NameToUnix/releases/latest/download/ntu-linux-x86_64.tar.gz
|
|
tar xzf ntu-linux-x86_64.tar.gz
|
|
sudo mv ntu /usr/local/bin/
|
|
|
|
# macOS Intel
|
|
wget https://github.com/jamulix/NameToUnix/releases/latest/download/ntu-macos-x86_64.tar.gz
|
|
tar xzf ntu-macos-x86_64.tar.gz
|
|
sudo mv ntu /usr/local/bin/
|
|
|
|
# macOS Apple Silicon (M1/M2)
|
|
wget https://github.com/jamulix/NameToUnix/releases/latest/download/ntu-macos-arm64.tar.gz
|
|
tar xzf ntu-macos-arm64.tar.gz
|
|
sudo mv ntu /usr/local/bin/
|
|
```
|
|
|
|
### Option 2: Build from Source
|
|
|
|
Die ausführbare Datei wird unter `target/release/ntu` erstellt. Du solltest sie mit 'sudo cp target/release/ntu /usr/local/bin/' kopieren. Sie ist dann für alle User verfügbar. Denke daran, die Konfiguationsdatei (s. u.) ebenfalls zu kopieren. Sie kann für jeden User individuell angepasst werden, wenn sie im home-Verzeichnis des Users liegt.
|
|
|
|
The executable file is created under `target/release/ntu`. You should copy it with 'sudo cp target/release/ntu /usr/local/bin/'. It is then available for all users. Remember to copy the configuration file (see below) as well. It can be customized for each user individually if it is located in the user's home directory.
|
|
|
|
```bash
|
|
git clone https://github.com/jamulix/NameToUnix.git # Download repository
|
|
cd NameToUnix # Change to download directory
|
|
cargo build --release # Build binary
|
|
sudo cp target/release/ntu /usr/local/bin/ # copy binary to local bin directory
|
|
|
|
# Globale Einstellungen / Global Settings
|
|
sudo mkdir -p /etc/NameToUnix/ # Create global config directory for NameToUnix in /etc
|
|
sudo cp .NameToUnix.conf /etc/NameToUnix/config.toml # Copy config file to this global directory
|
|
|
|
# Lokale Einstellungen / Local settings
|
|
mkdir -p ~/.config/NameToUnix/ # Create a personal config directory for NameToUnix
|
|
cp .NameToUnix.conf ~/.config/NameToUnix/config.toml # Copy config file to this personal directory
|
|
|
|
# Shell-Completion (optional)
|
|
sudo cp completions/ntu.bash /etc/bash_completion.d/ntu # Bash completion
|
|
# Oder für Zsh:
|
|
sudo cp completions/_ntu /usr/share/zsh/site-functions/_ntu # Zsh completion
|
|
# Oder für Fish:
|
|
sudo cp completions/ntu.fish /usr/share/fish/vendor_completions.d/ntu.fish # Fish completion
|
|
|
|
# Manpage (optional)
|
|
sudo cp man/ntu.1 /usr/share/man/man1/ # Install manual page
|
|
sudo mandb # Update man database
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# Basic usage (non-recursive: only immediate children)
|
|
ntu /path/to/files
|
|
|
|
# Recursive processing (process subdirectories)
|
|
ntu -r /path/to/files
|
|
|
|
# Dry-run: only preview the changes without actual renaming
|
|
ntu --dry-run -r /path/to/files
|
|
ntu -n -r /path/to/files # Short form
|
|
|
|
# Use specific config file
|
|
ntu --conf /path/to/custom.toml /path/to/files
|
|
|
|
# Process multiple paths
|
|
ntu -r /path1 /path2 /path3
|
|
|
|
# Exclude specific files
|
|
ntu -r -e "*.tmp" -e "backup_*" /path/to/files
|
|
|
|
# Process symlinks and special files (normally skipped)
|
|
ntu -r --special /path/to/files
|
|
|
|
# Increase verbosity
|
|
ntu -r -v /path/to/files
|
|
|
|
# Also rename the root directory
|
|
ntu -r --modify-root /path/to/files
|
|
|
|
# Combine options
|
|
ntu --dry-run -r -v --special /path/to/files
|
|
|
|
# Use lowercase sequence
|
|
ntu -r -s lower /path/to/files
|
|
|
|
# Minimal mode (only spaces, keep UTF-8)
|
|
ntu -s minimal /path/to/files
|
|
|
|
# UTF-8 friendly mode
|
|
ntu -s utf-8 /path/to/files
|
|
|
|
# List available sequences
|
|
ntu -L
|
|
|
|
# List sequences with details
|
|
ntu -L -v
|
|
```
|
|
|
|
**Note:** The following directories/files are automatically excluded:
|
|
`.git`, `.svn`, `node_modules`, `.cache`, `__pycache__`
|
|
|
|
## Verwendung
|
|
|
|
```bash
|
|
# Grundlegende Verwendung (nicht-rekursiv: nur direkte Kinder)
|
|
ntu /pfad/zu/dateien
|
|
|
|
# Rekursive Verarbeitung (Unterverzeichnisse verarbeiten)
|
|
ntu -r /pfad/zu/dateien
|
|
|
|
# Dry-run: Nur Vorschau der Änderungen ohne tatsächliche Umbenennung
|
|
ntu --dry-run -r /pfad/zu/dateien
|
|
ntu -n -r /pfad/zu/dateien # Kurzform
|
|
|
|
# Spezifische Config-Datei verwenden
|
|
ntu --conf /pfad/zu/custom.toml /pfad/zu/dateien
|
|
|
|
# Mehrere Pfade verarbeiten
|
|
ntu -r /pfad1 /pfad2 /pfad3
|
|
|
|
# Bestimmte Dateien ausschließen
|
|
ntu -r -e "*.tmp" -e "backup_*" /pfad/zu/dateien
|
|
|
|
# Symlinks und Special Files verarbeiten (normalerweise übersprungen)
|
|
ntu -r --special /pfad/zu/dateien
|
|
|
|
# Verbosity erhöhen
|
|
ntu -r -v /pfad/zu/dateien
|
|
|
|
# Auch das Wurzelverzeichnis umbenennen
|
|
ntu -r --modify-root /pfad/zu/dateien
|
|
|
|
# Optionen kombinieren
|
|
ntu --dry-run -r -v --special /pfad/zu/dateien
|
|
|
|
# Kleinbuchstaben-Sequenz verwenden
|
|
ntu -r -s lower /pfad/zu/dateien
|
|
|
|
# Minimal-Modus (nur Leerzeichen, UTF-8 behalten)
|
|
ntu -s minimal /pfad/zu/dateien
|
|
|
|
# UTF-8 freundlicher Modus
|
|
ntu -s utf-8 /pfad/zu/dateien
|
|
|
|
# Verfügbare Sequenzen auflisten
|
|
ntu -L
|
|
|
|
# Sequenzen mit Details auflisten
|
|
ntu -L -v
|
|
```
|
|
|
|
**Hinweis:** Die folgenden Verzeichnisse/Dateien werden automatisch ausgeschlossen:
|
|
`.git`, `.svn`, `node_modules`, `.cache`, `__pycache__`
|
|
|
|
## Configuration File / Konfiguration
|
|
|
|
Erstelle eine Datei `.NameToUnix.conf` im persönlichen Arbeitsverzeichnis z. B. mit folgendem Inhalt
|
|
(alternativ `~/.config/NameToUnix/config.toml`):
|
|
|
|
Create a file `.NameToUnix.conf` in your personal working directory, e.g. with the following content
|
|
(alternatively `~/.config/NameToUnix/config.toml`):
|
|
|
|
```toml
|
|
[replacements]
|
|
"foo" = "bar"
|
|
"old" = "new"
|
|
"alt" = "neu"
|
|
".." = "."
|
|
"_·_" = "_-_"
|
|
"Ä" = "Ae"
|
|
"Ö" = "Oe"
|
|
"Ü" = "Ue"
|
|
"ä" = "ae"
|
|
"ö" = "oe"
|
|
"ü" = "ue"
|
|
"ß" = "ss"
|
|
```
|
|
Dies ist eine Beispielkonfiguration. Du kannst Die Datei nach Belieben anpassen.
|
|
The above is an example configuration. You can customize the file as you wish.
|
|
|
|
Du solltest auch eine zentrale Konfigurationsdatei /etc/NameToUnix/config.toml im globalen Verzeichnis /etc erstellen (Beispiel):
|
|
You should also create a central configuration file /etc/NameToUnix/config.toml in the global directory /etc (example):
|
|
|
|
```toml
|
|
# /etc/NameToUnix/config.toml
|
|
# --------------------------------------------
|
|
# In dieser Datei können beliebige zusätzliche Schlüssel-Werte-Paare unter [replacements] hinterlegt werden,
|
|
# die im Dateistammnamen ersetzt werden. Zum Beispiel:
|
|
#
|
|
# [replacements]
|
|
# "foo" = "bar"
|
|
# "old" = "neu"
|
|
#
|
|
# Dadurch werden in den Dateinamen alle "foo" durch "bar" ersetzt, und "old" durch "neu".
|
|
# WICHTIG: Die hartcodierten Transformationen sind aber immer vorrangig und lassen sich auch nicht rückgängig machen.
|
|
# Die persönlichen Einstellungen überschreiben diese Einstellungen.
|
|
# VORSICHT! Zuerst mit 'ntu -n <path>' testen
|
|
# --------------------------------------------
|
|
# In this file, any additional key-value pairs can be stored under [replacements],
|
|
# which are replaced in the file master name. For example:
|
|
#
|
|
# [replacements]
|
|
# “foo” = “bar”
|
|
# “old” = “new”
|
|
#
|
|
# This replaces all “foo” with “bar” and “old” with “new” in the file names.
|
|
# IMPORTANT: The hard-coded transformations always have priority and cannot be undone.
|
|
# The personal settings overwrite these settings.
|
|
|
|
# BE CAREFUL! First test with 'ntu -n <path>' (Just display the changes)
|
|
|
|
[replacements]
|
|
".." = "."
|
|
"_·_" = "_-_"
|
|
".-_" = "_-_"
|
|
# "" = "" # bewirkt nichts / Dummy entry
|
|
```
|
|
|
|
|
|
### Verwendung von NameToUnix
|
|
|
|
Um die Verwendung von `ntu` zu verstehen, kannst du die folgende Hilfe ausgeben:
|
|
|
|
```text
|
|
ntu --help
|
|
```
|
|
|
|
Die Ausgabe sieht wie folgt aus:
|
|
|
|
```text
|
|
Ein Tool zum Anpassen von Verzeichnis- und Dateinamen an Linux-Konventionen
|
|
|
|
Usage: ntu [OPTIONS] [PATHS]...
|
|
|
|
Arguments:
|
|
[PATHS]... Pfade (Dateien und Verzeichnisse) zum rekursiven Anpassen
|
|
|
|
Options:
|
|
-q, --quiet Ausgaben unterdrücken (keine Umbenennungsinfos auf stdout)
|
|
-n, --dry-run Nur anzeigen, aber keine realen Änderungen vornehmen (dry-run)
|
|
-f, --force Existierende Dateien überschreiben
|
|
-e, --exclude <PATTERN> Zu ignorierende Muster (-e "*.py", mehrere können angegeben werden)
|
|
-v, --verbose Ausführliche Debug-Informationen
|
|
--modify-root Erlaubt, auch das Wurzelverzeichnis anzupassen
|
|
--special Auch symbolische Links und Special Files verarbeiten
|
|
-h, --help Print help
|
|
-V, --version Print version
|
|
|
|
```
|
|
|
|
### Usage of NameToUnix
|
|
|
|
```text
|
|
A tool for adapting directories and file names to Linux conventions
|
|
|
|
Usage: ntu [OPTIONS] [PATHS]...
|
|
|
|
Arguments:
|
|
[PATHS]... Paths (files and directories) for recursive customization
|
|
|
|
Options:
|
|
-q, --quiet Suppress output (no renaming info on stdout)
|
|
-n, --dry-run Only display, but do not make any real changes (dry-run)
|
|
-f, --force Overwrite existing files
|
|
-e, --exclude <PATTERN> Patterns to be ignored (-e "*.py", several can be specified)
|
|
-v, --verbose Detailed debug information
|
|
--modify-root Allows you to customize the root directory as well
|
|
--special Also process symbolic links and special files
|
|
-h, --help Print help
|
|
-V, --version Print version
|
|
|
|
```
|
|
|
|
## Test
|
|
|
|
Im Verzeichnis [***./test***](./test) gibt es ein bash-Skript [***create_test_tree.sh***](test/create_test_tree.sh), das lokal 21 Test-Verzeichnisse und 400 Dateien mit skurrilen Zufallsnamen erzeugt. Damit kannst Du ***NameToUnix*** ausprobieren:
|
|
|
|
***ntu -n ./testverzeichnis*** (nur Anzeige der Änderungen)
|
|
oder
|
|
***ntu ./testverzeichnis*** (Anzeige mit Umbenennen).
|
|
|
|
|
|
In the directory [***./test***](./test) there is a bash script [***create_test_tree.sh***](test/create_test_tree.sh), which locally creates 21 test directories and 400 files with bizarre random names. You can use this to try out ***NameToUnix***:
|
|
|
|
***ntu -n ./testverzeichnis*** (display changes only)
|
|
or
|
|
***ntu ./testverzeichnis*** (display with renaming).
|
|
|
|
## Lizenz / License
|
|
|
|
This project is licensed under the MIT license - see the [LICENSE](LICENSE) file for details.
|
|
|
|
Dieses Projekt steht unter der MIT-Lizenz - siehe die [LICENSE](LICENSE)-Datei für Details.
|
|
|
|
## Mitwirken / Contributions
|
|
|
|
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on the pull request process.
|
|
|
|
Beiträge sind willkommen! Bitte lies [CONTRIBUTING.md](CONTRIBUTING.md) für Details zum Prozess für Pull Requests.
|
|
|