xargs

build and execute command line[s]

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 blanks protected with apostrophes, quotes or a backslash).

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

‑‑max‑args=max‑args
-n max‑args
At most max‑args arguments are used per command line.
Use --max-args=1 to have a seperate command generated for each argument.

> ls -1 b* | xargs echo +
+b1 b2 b3
> ls -1 b* | xargs -max-args=1 echo +
+b1
+b2
+b3
Fewer than max‑args arguments will be used if max-chars is exceeded, unless ‑‑exit is given, in which case xargs exits.

‑‑repl[=repl‑str]
[repl‑str]
Without this option, STDIN‑args are appended to the command's arguments.
Use STDIN‑args to replace occurences of repl‑str in the common-args.
Unquoted blanks do not terminate arguments.
Default {}
(like for find -exec)
Implies ‑‑exit and ‑‑max‑lines=1.
-J repl-str

BSD (darwin too)

first occurrence of repl-str in STDIN‑args is replaced.
not defaulted to {} as in linux.
-I replstr

BSD (darwin too)

one or more occurrences of replstr are replaced in command with the entire line of input resulting in a maximun of 255 bytes.
by concatenating as much of the argument containing replstr as possible.
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 be useful
-R rep#

BSD (darwin too)

Number of replacments for -I. Default: 5 Will not affect how many arguments will be read from input (-n), or
the size of the command(s) xargs will generate (-s).
repl-str must occur as a distinct argument, not within a quoted string.

Example: 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

‑‑verbose
-t
Display the constructed command on STDERR before executing it.
‑‑interactive
-p
Prompt before running each command.
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.
Useful when STDIN‑args, like filenames, contain spaces, quote marks, or backslashes.
find -print0 is compatible with -0.

", \ etc are not special (all characters are taken literally).
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.
Default: command is run once 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.
> xargs --help
Usage: xargs [-0prtx] [--interactive] [--null] [-d|--delimiter=delim]
       [-E eof-str] [-e[eof-str]]  [--eof[=eof-str]]
       [-L max-lines] [-l[max-lines]] [--max-lines[=max-lines]]
       [-I replace-str] [-i[replace-str]] [--replace[=replace-str]]
       [-n max-args] [--max-args=max-args]
       [-s max-chars] [--max-chars=max-chars]
       [-P max-procs]  [--max-procs=max-procs] [--show-limits]
       [--verbose] [--exit] [--no-run-if-empty] [--arg-file=file]
       [--version] [--help] [command [initial-arguments]]

Report bugs to <bug-findutils@gnu.org>.
usage: xargs [-0opt] [-E eofstr] [-I replstr [-R replacements]] [-J replstr]
             [-L number] [-n number [-x]] [-P maxprocs] [-s size]
             [utility [argument ...]]
‑‑version
xargs (GNU findutils) 4.4.2
Copyright (C) 2007 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later 
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Written by Eric B. Decker, James Youngman, and Kevin Dalley.
Built using GNU gnulib version e5573b1bad88bfabcda181b9e0125fb0c52b7d3b

examples:

To delete ALL backup files (those with trailing ~) 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.