Manual pages: order NOTES / HISTORY / BUGS / EXAMPLE consistently

[thirdparty/util-linux.git] / misc-utils / rename.1

diff --git a/misc-utils/rename.1 b/misc-utils/rename.1
index d2c3d1421aea6c1490936563a5835bc8cf028ef4..64c70f7e4ea1c9381a0160ff4f33da5fda744bdb 100644 (file)
--- a/misc-utils/rename.1
+++ b/misc-utils/rename.1
@@ -1,12 +1,13 @@
 .\" Written by Andries E. Brouwer (aeb@cwi.nl)
 .\" Placed in the public domain
 .\"
-.TH RENAME "1" "June 2011" "util-linux" "User Commands"
+.TH RENAME 1 "June 2011" "util-linux" "User Commands"
 .SH NAME
 rename \- rename files
 .SH SYNOPSIS
 .B rename
-[\fIoptions\fR] \fIexpression replacement file\fR...
+[options]
+.IR "expression replacement file" ...
 .SH DESCRIPTION
 .B rename
 will rename the specified files by replacing the first occurrence of
@@ -15,22 +16,82 @@ in their name by
 .IR replacement .
 .SH OPTIONS
 .TP
-\fB\-v\fR, \fB\-\-verbose\fR
-Give visual feedback which files where renamed, if any.
+.BR \-s , " \-\-symlink"
+Do not rename a symlink but its target.
 .TP
-\fB\-V\fR, \fB\-\-version\fR
+.BR \-v , " \-\-verbose"
+Show which files were renamed, if any.
+.TP
+.BR \-n , " \-\-no\-act"
+Do not make any changes; add
+.B \-\-verbose
+to see what would be made.
+.TP
+.BR \-o , " \-\-no\-overwrite"
+Do not overwrite existing files.  When
+.B \-\-symlink
+is active, do not overwrite symlinks pointing to existing targets.
+.TP
+.BR \-i , " \-\-interactive"
+Ask before overwriting existing files.
+.TP
+.BR \-V , " \-\-version"
 Display version information and exit.
 .TP
-\fB\-h\fR, \fB\-\-help\fR
-Display help screen and exit.
-.SH EXAMPLES
+.BR \-h , " \-\-help"
+Display help text and exit.
+.SH WARNING
+The renaming has no safeguards by default or without any one of the options
+.B \-\-no-overwrite\fR,
+.B \-\-interactive
+or
+.B \-\-no\-act\fR.
+If the user has
+permission to rewrite file names, the command will perform the action without
+any questions.  For example, the result can be quite drastic when the command
+is run as root in the /lib directory.  Always make a backup before running the
+command, unless you truly know what you are doing.
+.SH INTERACTIVE MODE
+As most standard utilities rename can be used with a terminal device (tty in
+short) in canonical mode, where the line is buffered by the tty and you press
+ENTER to validate the user input.  If you put your tty in cbreak mode however,
+rename requires only a single key press to answer the prompt.  To set cbreak
+mode, run for example:
+.RS
+.PP
+.nf
+sh \-c 'stty \-icanon min 1; "$0" "$@"; stty icanon' rename \-i from to files
+.fi
+.PP
+.RE
+.SH EXIT STATUS
+.RS
+.PD 0
+.TP
+.B 0
+all requested rename operations were successful
+.TP
+.B 1
+all rename operations failed
+.TP
+.B 2
+some rename operations failed
+.TP
+.B 4
+nothing was renamed
+.TP
+.B 64
+unanticipated error occurred
+.PD
+.RE
+.SH EXAMPLE
 Given the files
 .IR foo1 ", ..., " foo9 ", " foo10 ", ..., " foo278 ,
 the commands
 .RS
 .PP
 .nf
-rename foo foo0 foo?
+rename foo foo00 foo?
 rename foo foo0 foo??
 .fi
 .PP
@@ -46,15 +107,17 @@ rename .htm .html *.htm
 .PP
 .RE
 will fix the extension of your html files.
-.SH WARNING
-The rename has no safeguards. If user has permission to rewrite file names
-the command will perform the action without any questions. For example
-result can be quite drastic when the command is ran as root in /lib
-directory. Make always a backup before running the command, unless you truly
-know what you are doing.
-.SH "SEE ALSO"
-.BR mmv (1),
+Provide an empty string for shortening:
+.RS
+.PP
+.nf
+rename '_with_long_name' '' file_with_long_name.*
+.fi
+.PP
+.RE
+will remove the substring in the filenames.
+.SH SEE ALSO
 .BR mv (1)
 .SH AVAILABILITY
 The rename command is part of the util-linux package and is available from
-ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
+https://www.kernel.org/pub/linux/utils/util-linux/.