xargs - build and execute command lines

xargs [-P max‑procs] [‑‑max‑procs=max‑procs] [command [common-args]] STDIN‑args
[‑i[replace‑str]] [‑‑replace[=replace‑str]]
[-l[max‑lines]] [‑‑max‑lines[=max‑lines]]
[‑s max‑chars] [‑‑max‑chars=max‑chars]
[‑n max‑args] [‑‑max‑args=max‑args]
[‑r ] [‑‑no-run-if-empty]
[-e[eof-str]] [‑‑eof[=eof-str]]
[‑p ] [‑‑interactive]
[-t ] [‑‑verbose]
[‑0] [‑‑null]
[‑‑help] [‑‑version]
[‑x] [‑‑exit]

  1. reads STDIN‑args (frequently from find) from standard input
  2. constructs a command with common-args followed by STDIN‑args
  3. executes the constructed command
STDIN‑args are delimited by blanks (unless protected with apostrophes, quotes or a backslash)

Blank lines in standard input are ignored.
Default command is echo

‑‑replace[=replace‑str]
[replace‑str]
Use STDIN‑args to replace occurences of replace‑str in the common-args,
instead of appending the STDIN‑args at the end.
Unquoted blanks do not terminate arguments.
Default {}
(like for find -exec)
Implies ‑‑exit and ‑‑max‑lines=1.
-J replace-str

darwin

Use STDIN‑args to replace the first occurrence of replace-str
Will not affect how many arguments will be read from input (-n), or
the size of the command(s) xargs will generate (-s).
replace-str must occur as a distinct argument. It will not be recognized if it is in the middle of a quoted string.

For example, to copy the list of files and directories which start with an uppercase letter in the current directory to destdir:

/bin/ls -1d [A-Z]* | xargs -J % cp % destdir

-I replstr

darwin

Execute command for each input line, replacing one or more occurrences of replstr in up to rep# (or 5 if no -R is specified) arguments to command with the entire line of input.
The resulting arguments will not exceede 255 bytes; this is implemented by concatenating as much of the argument containing replstr as possible, to the constructed arguments to command, up to 255 bytes. The 255 byte limit does not apply to arguments to command which do not contain replstr. No replacement will be done on command itself.
Implies -x. (Perhaps using -n 1 will help)
-R rep#

darwin

Number of replacments for -I
‑‑max‑args=max‑args
-n max‑args
Use at most max‑args arguments per command line.
Use --max-args=1 to have a seperate command generated for each argument.
Fewer than max‑args arguments will be used if max-chars is exceeded, unless ‑‑exit is given, in which case xargs exits.
‑‑verbose
-t
Display the constructed command on STDERR before executing it.
‑‑interactive
-p
Prompt before running each command, response starts with y or Y to execute.
Implies ‑‑verbose.
‑‑null
-0
STDIN‑args (most likely piped from another process ike find) are terminated by a null instead of by whitespace.
This allows processing of filenames with embedded special characters which.
", \ etc are not special (all characters are taken literally).
Useful when STDIN‑args, like filenames, contain spaces, quote marks, or backslashes.
find -print0 is compatible with -0.

Disables the eof-str.

--arg-file=file
-a file

GNU

Read items from file instead of standard input.
stdin is unchanged when commands are run. Otherwise, stdin is redirected from /dev/null.
--delimiter=delim
-d delim

GNU

Input items are terminated by delim, Quotes and backslash are not special; characters in the input are taken literally.
Disables the end-of-file string, which is treated like any other argument.
Used when the input consists of newline separated items, (it is prefered to write a program to use '--null')
delim may be a single character, a shell escape such as \n,
or an octal or hexadecimal escape code, as for printf. Multibyte characters are not supported.
-Eeof-str
‑‑eof[=eof-str]
-e[eof-str]
Processing an input file is stopped when eof-str is encountered.
If eof-str is omitted, there is no end-of file string.
‑‑max‑chars=max‑chars
-s max‑chars
Use at most max‑chars characters per command line, including the command and common arguments and the terminating nulls at the ends of the argument strings. The default is as large as possible, up to 20k characters.
‑‑max‑lines[=max‑lines]
-l[max‑lines]
Use at most max‑lines nonblank input lines per command line, default :1
Trailing blanks cause an input line to be logically continued on the next input line!
Implies ‑‑exit.
‑‑no-run-if-empty
-r
If STDIN‑arg does not contain strings, do not run the command.
Normally, the command is run once even if there is no input.
‑‑exit
-x
Exit if the max-chars is exceeded. Use ‑‑max‑args with ‑‑interactive; otherwise chances are that only one exec will be done.
‑‑max‑procs=max‑procs
-P max‑procs
Run up to max‑procs processes at a time; the default is 1.
If max‑procs is 0(bad), xargs will run as many processes as possible at a time.
This will cause the system_process_table to fill up resulting in some process (not necessarily your's) partially completing, some being skipped and general mayhem.
If a process sub-shells a dozen times and xargs starts 100, that's 1200! See ulimit
‑‑help Output a summary of the options to xargs and exit.
‑‑version Output the version number of xargs and exit.

examples:

To delete ALL backup files in all subdirectories (not just the current working directory):

/usr/bin/find . -iname "*~" | xargs rm

To list all html files that contain js with most recently updated displayed last:

grep --files-with-matches js *.html | xargs ls -lrt --max-args=1 {}

exit status

0 success
123 command exited with status in range of 1 - 125
124 command exited with status 255
125 command killed by signal (?)
126 command cannot be run because (?)
127 command is not found
1 some other error occurred.

Caution

When using find to create STDIN‑args on a directory with a active file creates/deletes,
xargs may attempt to operate on non-existant files or miss files just created.

See find, locate, locatedb, updatedb.