dschlueter/ntu
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
ntu/man/ntu.1
dschlueter b84dd70f80 feat: Add --max-depth option and safe symlink handling (v1.2.0) 
## Neue Features

- **--max-depth N**: Begrenzt Rekursionstiefe auf N Ebenen (erfordert -r)
  - Nützlich für sehr tiefe Verzeichnisbäume (z.B. node_modules)
  - Verhindert unnötige Traversierung tiefer Strukturen

- **Explizites Symlink-Handling**:
  - Standard: Symlinks werden komplett übersprungen (sicher)
  - Mit --special: Nur Symlink-Namen werden bereinigt, Ziel bleibt unangetastet
  - follow_links(false) explizit gesetzt zur Vermeidung von Endlosschleifen
  - Verhindert unbeabsichtigte Änderungen außerhalb des Zielverzeichnisses

- **Verbose Symlink-Logging**: Zeigt mit -v welche Symlinks übersprungen werden

## Tests

- 5 neue Integration-Tests hinzugefügt:
  - test_max_depth_option
  - test_max_depth_requires_recursive
  - test_symlinks_default_behavior (Unix only)
  - test_symlinks_with_special_flag (Unix only)
  - test_symlinks_not_followed (Unix only)

- Alle 30 Tests bestehen (25 bestehende + 5 neue)

## Dokumentation

- README.md: Neue Beispiele und "Symlink Behavior" Sektion
- CHANGELOG.md: v1.2.0 Eintrag mit allen Änderungen
- man/ntu.1: --max-depth Option und SYMLINK BEHAVIOR Sektion
- CLAUDE.md: Aktualisierte Code-Architektur Dokumentation

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-12 13:39:41 +01:00

224 lines
6.4 KiB
Groff
Raw Blame History

.TH NTU 1 "2025-02-12" "NameToUnix 1.2.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
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
.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 (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://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
Reference in a new issue View git blame Copy permalink