ntu/man/ntu.1

.TH NTU 1 "2026-02-13" "NameToUnix 1.2.1" "User Commands"
.SH NAME
ntu \- sanitize file and directory names to Unix conventions
.SH SYNOPSIS
.B ntu
[\fIOPTIONS\fR] \fIPATH\fR...
.SH DESCRIPTION
.B 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.
.PP
By default, the tool processes only the specified paths and their immediate
children. Use the \fB\-r\fR 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.
.SH OPTIONS
.TP
.BR \-r ", " \-\-recursive
Process directories recursively (default: only immediate children)
.TP
.BR \-\-max\-depth " \fIN\fR"
Limit recursion to N levels deep (requires \fB\-r\fR). Useful for processing only a few levels of a deep directory tree (e.g., limiting node_modules traversal).
.TP
.BR \-s ", " \-\-sequence " \fINAME\fR"
Use a specific transformation sequence. Available sequences: default, lower, upper, minimal, utf-8. Use \fB\-L\fR to list all sequences.
.TP
.BR \-L
List all available transformation sequences. Use with \fB\-v\fR for detailed information.
.TP
.BR \-\-conf " \fIFILE\fR"
Use a specific configuration file instead of the default hierarchy
.TP
.BR \-q ", " \-\-quiet
Suppress output (no rename information on stdout)
.TP
.BR \-n ", " \-\-dry\-run
Show what would be renamed without making actual changes (alias: \-\-no\-changes)
.TP
.BR \-f ", " \-\-force
Overwrite existing files if target already exists
.TP
.BR \-e ", " \-\-exclude " \fIPATTERN\fR"
Exclude files matching glob pattern (can be specified multiple times)
.TP
.BR \-v ", " \-\-verbose
Show verbose debug information
.TP
.BR \-\-modify\-root
Allow renaming of the root directory itself (normally skipped)
.TP
.BR \-\-special
Process symbolic links and special files (normally skipped)
.TP
.BR \-\-no\-color
Disable colored output. The \fBNO_COLOR\fR environment variable is also
respected (see \fIhttps://no-color.org/\fR).
.TP
.BR \-h ", " \-\-help
Print help information
.TP
.BR \-V ", " \-\-version
Print version information
.SH TRANSFORMATIONS
.B ntu
applies the following transformations to filenames:
.TP
.B Spaces
Replaced with underscores (_)
.TP
.B German Umlauts
ä → ae, ö → oe, ü → ue, Ä → Ae, Ö → Oe, Ü → Ue, ß → ss
.TP
.B Special Characters
Most special characters are replaced with underscores. Some are preserved
in specific contexts (e.g., C++ is kept intact).
.TP
.B Hidden Files
Files starting with a dot (.) are recognized and preserved correctly.
.TP
.B Double Extensions
Extensions like .tar.gz, .tar.bz2, .tar.xz are preserved as a unit.
.TP
.B Parentheses
Replaced with underscores.
.TP
.B Multiple Underscores
Consecutive underscores are collapsed to a single underscore.
.SH SEQUENCES
.B ntu
supports different transformation sequences that can be selected with the \fB\-s\fR option:
.TP
.B default
Standard transformation: spaces become underscores, German umlauts are converted
to ASCII equivalents, special characters are removed or replaced.
.TP
.B lower
Like default, but converts all text to lowercase.
.TP
.B upper
Like default, but converts all text to UPPERCASE.
.TP
.B minimal
Minimal changes: only replaces spaces with underscores, keeps umlauts and
other UTF-8 characters.
.TP
.B utf-8
UTF-8 friendly: keeps umlauts and UTF-8 characters, replaces spaces,
removes special characters.
.SH EXCLUDED PATTERNS
By default, the following directories are automatically excluded:
.PP
.nf
.RS
.git/, .svn/, node_modules/, .cache/, __pycache__/
.RE
.fi
.PP
Additional patterns can be excluded using the \fB\-e\fR option.
.SH PARALLEL PROCESSING
For directories with 100 or more files, \fBntu\fR automatically uses
parallel processing to improve performance. For smaller directories,
it processes files sequentially to avoid overhead.
.SH EXAMPLES
.TP
Rename files in current directory (dry-run):
.B ntu \-n .
.TP
Rename files in specific directory:
.B ntu /path/to/directory
.TP
Exclude specific patterns:
.B ntu \-e "*.tmp" \-e "*.bak" /path/to/directory
.TP
Force overwrite existing files:
.B ntu \-f /path/to/directory
.TP
Process multiple directories:
.B ntu /path/one /path/two /path/three
.TP
Verbose output with no colors:
.B ntu \-v \-\-no\-color /path/to/directory
.TP
Use lowercase sequence:
.B ntu \-r \-s lower /path/to/files
.TP
Minimal mode (only spaces, keep UTF-8):
.B ntu \-s minimal /path/to/files
.TP
UTF-8 friendly mode:
.B ntu \-s utf-8 /path/to/files
.TP
List all available sequences:
.B ntu \-L
.TP
List sequences with details:
.B ntu \-L \-v
.TP
Limit recursion depth to 3 levels:
.B ntu \-r \-\-max\-depth 3 /path/to/files
.TP
Process symlink names (but don't follow them):
.B ntu \-r \-\-special /path/to/files
.SH SYMLINK BEHAVIOR
By default, \fBntu\fR does not process symbolic links:
.IP \(bu 2
Symlinks are skipped (not renamed, not followed)
.IP \(bu 2
Prevents unintended changes outside the target directory
.IP \(bu 2
No risk of infinite loops from circular symlinks
.PP
With the \fB\-\-special\fR flag:
.IP \(bu 2
Symlink names are sanitized (e.g., "link to file" \(-> "link_to_file")
.IP \(bu 2
Symlinks are still not followed (targets remain unchanged)
.IP \(bu 2
Safe: only the link itself is renamed, not what it points to
.SH CONFIGURATION
.B ntu
looks for configuration files in the following locations. Later files
override earlier ones (highest priority last):
.PP
.nf
.RS
1. /etc/NameToUnix/config.toml    (system-wide, lowest priority)
2. ~/.config/NameToUnix/config.toml  (user-specific)
3. ./.NameToUnix.conf             (working directory, highest priority)
.RE
.fi
.PP
When using \fB\-\-conf\fR, the standard hierarchy is bypassed and only the
specified file is loaded.
.PP
Configuration files use TOML format with a \fB[replacements]\fR section
for custom character replacements. See the project documentation for details.
.SH ENVIRONMENT
.TP
.B NO_COLOR
When set (to any value), colored output is disabled. This follows the
convention described at \fIhttps://no-color.org/\fR. The \fB\-\-no\-color\fR
flag has the same effect.
.SH EXIT STATUS
.TP
.B 0
Success
.TP
.B 1
Error occurred during processing
.SH SAFETY
.B ntu
performs several safety checks:
.IP \(bu 2
Checks if target file already exists (unless \fB\-\-force\fR is used)
.IP \(bu 2
Verifies write permissions before attempting rename
.IP \(bu 2
Processes files from deepest to shallowest to avoid parent conflicts
.IP \(bu 2
Skips special files unless explicitly requested with \fB\-\-special\fR
.SH BUGS
Report bugs at: https://kitux.de/forgejo/dschlueter/ntu/issues
.SH AUTHOR
Written by Dieter Schlüter <dschlueter@kitux.de>
.SH COPYRIGHT
Copyright \(co 2025 Dieter Schlüter. Licensed under MIT License.
.SH SEE ALSO
.BR rename (1),
.BR detox (1),
.BR mv (1)
.PP
Full documentation at: https://kitux.de/forgejo/dschlueter/ntu