NTU(1)

NAME
ntu - sanitize file and directory names to Unix conventions

SYNOPSIS
ntu [OPTIONS] PATH...

DESCRIPTION
ntu (NameToUnix) is a command-line tool that renames files and directories to make them compatible with Unix/Linux naming conventions. It replaces spaces with underscores, converts German umlauts to their ASCII equivalents, and removes or replaces problematic special characters.

By default, the tool processes only the specified paths and their immediate children. Use the -r flag to enable recursive processing of subdirectories. When recursive, it starts from the deepest level to avoid conflicts with parent directory renames. It preserves file extensions, including double extensions like .tar.gz, and handles hidden files correctly.

OPTIONS

-r, --recursive
    Process directories recursively (default: only immediate children)

-s, --sequence NAME
    Use a specific transformation sequence. Available sequences: default, lower, upper, minimal, utf-8. Use -L to list all sequences.

-L  List all available transformation sequences. Use with -v for detailed information.

--conf FILE
    Use a specific configuration file instead of the default hierarchy

-q, --quiet
    Suppress output (no rename information on stdout)

-n, --dry-run
    Show what would be renamed without making actual changes (alias: --no-changes)

-f, --force
    Overwrite existing files if target already exists

-e, --exclude PATTERN
    Exclude files matching glob pattern (can be specified multiple times)

-v, --verbose
    Show verbose debug information

--modify-root
    Allow renaming of the root directory itself (normally skipped)

--special
    Process symbolic links and special files (normally skipped)

--no-color
    Disable colored output

-h, --help
    Print help information

-V, --version
    Print version information

TRANSFORMATIONS
ntu applies the following transformations to filenames:

Spaces
    Replaced with underscores (_)

German Umlauts
    ä → ae, ö → oe, ü → ue, Ä → Ae, Ö → Oe, Ü → Ue, ß → ss

Special Characters
    Most special characters are replaced with underscores. Some are preserved in specific contexts (e.g., C++ is kept intact).

Hidden Files
    Files starting with a dot (.) are recognized and preserved correctly.

Double Extensions
    Extensions like .tar.gz, .tar.bz2, .tar.xz are preserved as a unit.

Parentheses
    Replaced with underscores.

Multiple Underscores
    Consecutive underscores are collapsed to a single underscore.

SEQUENCES
ntu supports different transformation sequences that can be selected with the -s option:

default
    Standard transformation: spaces become underscores, German umlauts are converted to ASCII equivalents, special characters are removed or replaced.

lower
    Like default, but converts all text to lowercase.

upper
    Like default, but converts all text to UPPERCASE.

minimal
    Minimal changes: only replaces spaces with underscores, keeps umlauts and other UTF-8 characters.

utf-8
    UTF-8 friendly: keeps umlauts and UTF-8 characters, replaces spaces, removes special characters.

EXCLUDED PATTERNS
By default, the following directories are automatically excluded:

Additional patterns can be excluded using the -e option.

PARALLEL PROCESSING
For directories with 100 or more files, ntu automatically uses parallel processing to improve performance. For smaller directories, it processes files sequentially to avoid overhead.

EXAMPLES

Rename files in current directory (dry-run):
    ntu -n .

Rename files in specific directory:
    ntu /path/to/directory

Exclude specific patterns:
    ntu -e *.tmp -e *.bak /path/to/directory

Force overwrite existing files:
    ntu -f /path/to/directory

Process multiple directories:
    ntu /path/one /path/two /path/three

Verbose output with no colors:
    ntu -v --no-color /path/to/directory

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 all available sequences:
    ntu -L

List sequences with details:
    ntu -L -v

CONFIGURATION
ntu looks for configuration files in the following locations (in order):

    ~/.config/NameToUnix/config.toml
    /etc/NameToUnix/config.toml

Configuration files can customize character replacements and other behavior. See the project documentation for configuration file format.

EXIT STATUS

0   Success

1   Error occurred during processing

SAFETY
ntu performs several safety checks:

•   Checks if target file already exists (unless --force is used)

•   Verifies write permissions before attempting rename

•   Processes files from deepest to shallowest to avoid parent conflicts

•   Skips special files unless explicitly requested with --special

BUGS
Report bugs at: https://github.com/jamulix/NameToUnix/issues

AUTHOR
Written by Dieter Schlüter <dieter.schlueter@linix.de>

COPYRIGHT
Copyright © 2025 Dieter Schlüter. Licensed under MIT License.

SEE ALSO
rename(1), detox(1), mv(1)

Full documentation at: https://github.com/jamulix/NameToUnix