5f283b0fb1
Neue Features seit 0.2.0: - CI/CD Pipeline mit automatischen Builds - Shell-Completions für Bash, Zsh und Fish - Professionelle Manpage - Farbige Terminal-Ausgabe - 13 Integration-Tests Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
149 lines
4.1 KiB
Groff
149 lines
4.1 KiB
Groff
.TH NTU 1 "2025-02-10" "NameToUnix 0.3.0" "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
|
|
The tool processes files recursively, starting 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 \-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
|
|
.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 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
|
|
.SH CONFIGURATION
|
|
.B ntu
|
|
looks for configuration files in the following locations (in order):
|
|
.PP
|
|
.nf
|
|
.RS
|
|
./.NameToUnix.conf
|
|
~/.config/NameToUnix/config.toml
|
|
/etc/NameToUnix/config.toml
|
|
.RE
|
|
.fi
|
|
.PP
|
|
Configuration files can customize character replacements and other behavior.
|
|
See the project documentation for configuration file format.
|
|
.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://github.com/jamulix/NameToUnix/issues
|
|
.SH AUTHOR
|
|
Written by Dieter Schlüter <dieter.schlueter@linix.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://github.com/jamulix/NameToUnix
|