INPLACE(1) - General Commands Manual

NAME

inplace - edits files in-place through given filter commands

SYNOPSIS

inplace [-DLfinstvz] [-b suffix] -e commandline [[-e commandline] …] [file …]
inplace [-DLfinstvz] [-b suffix] commandline [file …]

DESCRIPTION

The inplace 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.

Inode numbers will change by default, but there is a -i option with which given the inode number of each edited file will be preserved.

As for filter commands, a single command may be specified as the first argument to inplace. To pass many filter commands, specify each followed by the -e option.

There are some cases where inplace does not replace a file, such as when:

The original file is not writable (use -f to force editing against read-only files)
A filter command fails and exits with a non-zero return code
The resulted output is identical to the original file
The resulted output is empty (use -z to accept empty output)

OPTIONS

The following command line arguments are supported:

-h

—help

Show help and exit.

-D

—debug

Turn on debug output.

-L

—dereference

By default, inplace ignores non-regular files including symlinks, but this switch makes it resolve (dereference) each symlink using realpath(3) and edit the original file.

-b SUFFIX

—backup-suffix SUFFIX

Create a backup file with the given suffix for each file. Note that backup files will be written over existing files, if any.

-e COMMANDLINE

—execute COMMANDLINE

Specify a filter command line to run for each file in which the following placeholders can be used:

%0

replaced by the original file path, shell escaped with \‘s as necessary

%1

replaced by the source file path, shell escaped with \‘s as necessary

%2

replaced by the destination file path, shell escaped with \‘s as necessary

%%

replaced by ‘%’

Omission of %2 indicates %1 should be modified destructively, and omission of both %1 and %2 implies “(...) < %1 > %2” around the command line.

When the filter command is run, the destination file is always an empty temporary file, and the source file is either the original file or a temporary copy file.

Every temporary file has the same suffix as the original file, so that file name aware programs can play nicely with it.

Instead of specifying a whole command line, you can use a command alias defined in a configuration file, ~/.inplace. See the FILES section for the file format.

This option can be specified many times, and they will be executed in sequence. A file is only replaced if all of them succeeds.

See the EXAMPLES section below for details.

-f

—force

By default,
**inplace**
does not perform editing if a file is not writable.  This switch makes
it force editing even if a file to process is read-only.

-i

—preserve-inode

Make sure to preserve the inode number of each file.

-n

—dry-run

Do not perform any destructive operation and just show what would have
been done.  This switch implies
**-v**.

-s

—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.

This switch can be effectively used when the temporary directory does
not have sufficient disk space for a resulted file.

If this option is specified, edited files will have newly assigned
inode numbers.  To prevent this, use the
**-i**
option.

-t

—preserve-timestamp

Preserve the access and modification times of each file.

-v

—verbose

Turn on verbose mode.

-z

—accept-empty

By default,
**inplace**
does not replace the original file when a resulted file is empty in
size because it is likely that there is a mistake in the filter
command.  This switch makes it accept empty (zero-sized) output and
replace the original file with it.

EXAMPLES

Sort files in-place using sort(1):

inplace sort file1 file2 file3
Below works the same as above, passing each input file via the command line argument:
inplace ‘sort %1 > %2’ file1 file2 file3
Perform in-place charset conversion and newline code conversion:

inplace -e ‘iconv -f EUC-JP -t UTF-8’ -e ‘perl -pe “s/$/\r/”’ file1 file2 file3
Process image files taking backup files:

inplace -b.orig ‘convert -rotate 270 -resize 50%% %1 %2’ *.jpg
Perform a mass MP3 tag modification without changing timestamps:

find mp3/Some_Artist -name ‘*.mp3’ -print0 | xargs -0 inplace -te ‘mp3info -a “Some Artist” -g “Progressive Rock” %1’
As you see above, inplace makes a nice combo with find(1) and xargs(1).

FILES

~/.inplace

The configuration file, which syntax is described as follows:

*	Each alias definition is a name/value pair separated with an
	"=",
	one per line.

*	White spaces at the beginning or the end of a line, and around
	assignment separators
	("=")
	are stripped off.

*	Lines starting with a
	"#"
	are ignored.

ENVIRONMENT

TMPDIR

TMP

TEMP

Temporary directory candidates where
**inplace**
attempts to create intermediate output files, in that order.  If none
is available and writable,
*/tmp*
is used.  If
**-s**
is specified, they will not be used.

AUTHORS

Akinori MUSHA [email protected]

BUGS

inplace cannot always preserve timestamps in full precision depending on the ruby interpreter and the platform that inplace runs on, that is, ruby 1.9 and later supports timestamps in nanoseconds but setting file timestamps in nanosecond precision is only possible if the platform supports utimensat(2).

So, a problem can arise if the file system supports nanoseconds, like ext4 and ZFS, but the platform does not have the system call to set timestamps in nanoseconds, like Linux < 2.6.22, glibc < 2.6 and FreeBSD, that the sub-microsecond part of a timestamp cannot be preserved.

FreeBSD - November 22, 2012