.\" $Idaemons: /home/cvs/inplace/inplace.1,v 1.8 2004/04/21 13:25:51 knu Exp $
.\" $Id$
.\"
.Dd April 7, 2004
.Dt INPLACE 1
.Os FreeBSD
.Sh NAME
.Nm inplace
.Nd edits files in-place through given filter commands
.Sh SYNOPSIS
.Nm
.Op Fl Lnstvz
.Op Fl b Ar suffix
.Fl e Ar commandline
.Op Oo Fl e Ar commandline Oc ...
.Op Ar file ...
.Nm
.Op Fl Lnstvz
.Op Fl b Ar suffix
.Ar commandline
.Op Ar file ...
.Sh DESCRIPTION
The
.Nm
command is a utility to edit files in-place through given filter
commands preserving the original file attributes.  Mode and ownership
(user and group) are preserved by default, and time (access and
modification) by choice.
.Pp
A single command may be specified as the first argument to
.Nm .
Multiple commands may be specified by using the
.Fl e
option.
.Pp
There are some cases where
.Nm
does not replace a file with the resulted file, such as when:
.Bl -enum -offset indent
.It
A filter command fails and exits with a non-zero return code
.It
The resulted output is identical to the original file
.It
The resulted output is empty (use
.Fl z
to accept empty output)
.El 
.Pp
.Sh OPTIONS
The following command line arguments are supported:
.Pp
.Bl -tag -width "--preserve-timestamp" -compact
.It Fl h
.It Fl -help
Show help and exit.
.Pp
.It Fl L
.It Fl -dereference
By default,
.Nm
ignores non-regular files including symlinks, but this switch makes it
dereference each symlink using realpath(3) and edit the original file.
.Pp
.It Fl b Ar SUFFIX
.It Fl -backup-suffix Ar SUFFIX
Create a backup file with the given suffix for each file.  Note that
backup files will be written over existing files, if any.
.Pp
.It Fl e Ar COMMANDLINE
.It Fl -execute Ar COMMANDLINE
Specify a filter command line to run for each file in which the following placeholders can be used:
.Bl -tag -offset indent -nested
.It Cm %0
replaced by the original file path
.It Cm %1
replaced by the source file path
.It Cm %2
replaced by the destination file path
.It Cm %%
replaced by
.Ql %
.El
.Pp
Missing %2 indicates %1 is modified destructively, and missing both %1
and %2 implies
.Dq Li "(...) < %1 > %2"
around the command line.
.Pp
The destination file is always a temporary file, and the source file
is either the original file or a temporary file.
.Pp
Placed file paths will be properly shell escaped with
.Pf \e 's
as necessary.
.Pp
This option can be specified many times, and they will be executed in
sequence.  A file is only replaced if all of them succeeds.
.Pp
See the EXAMPLES section below for details.
.Pp
.It Fl n
.It Fl -dry-run
Do not perform any destructive operation and just show what would have
been done.  This switch implies
.Fl v .
.Pp
.It Fl s
.It Fl -same-directory
Create a temporary file in the same directory as each replaced file.
This may speed up the performance when the directory in question is on
a partition that is fast enough and the system temporary directory is
slow.
.Pp
Another reason to use this switch is when the temporary directory does
not have sufficient disk space for a resulted file.
.Pp
.It Fl t
.It Fl -preserve-timestamp
Preserve the access and modification times of each file.
.Pp
.It Fl v
.It Fl -verbose
Turn on verbose mode.
.Pp
.It Fl z
.It Fl -accept-empty
By default,
.Nm
does not replace the original file when a resulted file is empty in
size.  This switch makes it accept empty (zero-sized) output and
replace the original file with it.
.El
.Sh EXAMPLES
.Bl -bullet
.It
Sort files in-place using
.Xr sort 1 :
.Pp
.Dl inplace sort file1 file2 file3
.Pp
Below is the same thing as above, except for passing input files via
the command line argument:
.Pp
.Dl inplace 'sort %1 > %2' file1 file2 file3
.Pp
.It
Perform in-place charset conversion and newline code conversion:
.Pp
.Dl inplace -e 'iconv -f EUC-JP -t UTF-8' -e 'perl -pe \&"s/$/\e\er/\&"' file1 file2 file3
.Pp
.It
Process image files taking backup files:
.Pp
.Dl inplace -b.orig 'convert -rotate 270 -resize 50%% %1 %2' *.jpg
.Pp
.It
Perform a mass MP3 tag modification without changing timestamps:
.Pp
.Dl find mp3/Some_Artist -name '*.mp3' -print0 | xarg -0 inplace -te 'mp3info -a \&"Some Artist\&" -g \&"Progressive Rock\&" %1'
.Pp
As you see above,
.Nm
makes a nice combo with
.Xr find 1
and
.Xr xargs 1 .
.Pp
.El
.Sh ENVIRONMENT
.Bl -tag -width "TMPDIR" -compact
.It Ev TMPDIR
.It Ev TMP
.It Ev TEMP
Temporary directory candidates where
.Nm 
attempts to create intermediate output files, in that order.  If none
is available and writable,
.Pa /tmp
is used.  If
.Fl s
is specified, they will not be used.
.El
.Sh SEE ALSO
.Xr find 1 ,
.Xr xargs 1 ,
.Xr realpath 3
.Sh AUTHORS
.An Akinori MUSHA Aq knu@iDaemons.org
.Sh BUGS
There may be.  Use at your own risk.