xargsx
Build and run command lines from standard input.
Mirrors GNU xargs. Run it as xargsx, or as gnux xargsx.
Synopsis
xargsx [OPTION]... [COMMAND [INITIAL-ARGUMENT]...]GNU reference
Description
xargsx reads items from standard input and runs COMMAND (echo when none is given) with the INITIAL-ARGUMENTs followed by the items, as many per command line as fit, until the input is used up. Items are separated by blanks and newlines; single quotes, double quotes and a backslash protect a character from being a separator, a quote must close on the line it opens on, and a blank line is ignored. Because file names may hold blanks, quotes and newlines, pair -0 with a producer that separates names with NUL (findx -print0), or use -d to name a single delimiter character (C escapes such as \n and \t, octal \NNN and hexadecimal \xHH are understood); with either, every other character is literal. -a reads the items from a file and leaves standard input to the commands; otherwise each command gets an empty standard input, so that it cannot consume the items. -E names a logical end-of-input item (not with -0 or -d). -n limits the items per command and -L the non-blank input lines per command (a line that ends in a blank continues on the next one). -s sets the size limit of a command line, counting the command, the initial arguments, the items and one terminating NUL for each: the default is 131072 bytes, or the system's limit when that is smaller, taken as 524288 bytes on Unix and 32767 on Windows, less 2048 and less the size of the environment. -x fails with 'argument list too long' when the items asked for with -n or -L do not fit, instead of running a shorter command. -I runs the command once per input line and replaces every REPLACE-STR in the command and its initial arguments with the line (leading blanks removed, quotes still processed); it implies -x and -L 1, and -L implies -x. Without -r the command runs once even when the input holds no items. -t prints each command line on the error stream before running it, quoted so that it can be pasted into a shell; -p prints it followed by '?...' and runs it only when the line read from the terminal (/dev/tty, or the console on Windows) begins with y or Y. -P runs up to MAX-PROCS commands at once; their output is not grouped, so lines of different commands may interleave. A command that exits with status 255, or that a signal ends, stops xargsx at once; any other nonzero status lets the remaining commands run and makes the final status 123.
Differences from GNU xargs: a COMMAND named after a gnux tool, by its own name (rmx) or its GNU name (rm, echo), runs inside the xargsx process instead of as a program found on PATH, so that 'xargsx rm' works where no GNU tools are installed; any other name is a program found on PATH. Use 'envx COMMAND' as the command to force the program on PATH. GNU's last-one-wins between conflicting options is replaced by a fixed precedence toward the most cautious one, in any order: -I/-i wins over -L/-l, which wins over -n, each with GNU's warning about the ignored option; -0 wins over -d; and of two spellings of one option, -I wins over -i, -L over -l and -E over -e. -P 0 runs at most 128 commands at once rather than as many as the system allows. The system's command-line limit is the fixed figure above, not one asked of the system. A NUL in the input outside -0 mode is dropped with GNU's warning, where GNU cuts the item short at it. A quote left open at the very end of the input is always an error. -o/--open-``tty and --process-slot-var are not supported and are refused with a usage error. Changing -P while xargsx runs, with SIGUSR1 and SIGUSR2, is not available.
Permissions
xargsx needs read permission on the -a file. Running a program needs execute permission on it and search permission on the directories leading to it; a gnux tool run in-process needs whatever that tool needs for the files it is given (rm needs write permission on the containing directory, and so on). The commands run with the privileges of xargsx itself.
Use cases
- Removing, moving or checksumming the files a search produced, a few commands for thousands of names.
- Handling file names with spaces, quotes or newlines safely with -0 and a NUL-separated producer.
- Running one command per input line with the line placed anywhere in it using
-I. - Splitting a long list into commands of N arguments with
-n. - Running independent jobs in parallel with
-P. - Reviewing destructive commands before they run with
-t, or approving each one with-p. - Keeping a command line under a size limit with
-swhen a program rejects long ones. - Skipping the command entirely when a search found nothing, with
-r. - Feeding items from a file with
-awhile the command keeps the terminal as its standard input. - Writing scripts that remove or copy files the same way on machines with no GNU tools installed.
Flags
-a, --arg-file FILE read arguments from FILE, not standard input
-d, --delimiter CHARACTER items in the input are separated by CHARACTER, not by whitespace;
disables quote and backslash processing and logical EOF processing
-e, --eof END[=" "]�equivalent to -E END if END is specified; otherwise, there is no end-of-file string
-E, --eof-string END set logical EOF string to END; if END occurs as an item of input,
the rest of the input is ignored (ignored if -0 or -d was specified)
-x, --exit exit if the size (see -s) is exceeded
--help display this help and exit
-p, --interactive prompt before running commands
-n, --max-args MAX-ARGS use at most MAX-ARGS arguments per command line
-s, --max-chars MAX-CHARS limit length of command line to MAX-CHARS
-L, --max-input-lines MAX-LINES use at most MAX-LINES non-blank input lines per command line
-l, --max-lines MAX-LINES[="1"] similar to -L but defaults to at most one non-blank input line
if MAX-LINES is not specified
-P, --max-procs MAX-PROCS run at most MAX-PROCS processes at a time
-r, --no-run-if-empty if there are no arguments, then do not run COMMAND;
if this option is not given, COMMAND will be run at least once
-0, --null items are separated by a NUL, not whitespace;
disables quote and backslash processing and logical EOF processing
-o, --open-tty reopen stdin as /dev/tty in the child process before executing
the command (not supported)
--process-slot-var VAR set environment variable VAR in child processes (not supported)
-i, --replace R[="{}"] replace R in INITIAL-ARGS with names read from standard input,
split at newlines; if R is unspecified, assume {}
-I, --replace-string R same as --replace=R
--show-limits show limits on command-line length
-t, --verbose print commands before executing them
--version output version information and exitExamples
Join the items of several lines into one command line
printfx 'a b\nc\n' | xargsx echoxRemove the files a search found, whatever characters their names hold
findx . -name '*.tmp' -print0 | xargsx -0 rmx -fDo nothing at all when the search finds no file
findx . -name '*.orig' -print0 | xargsx -0 -r rmxPass two items to each command
seqx 6 | xargsx -n 2 echoxRun one command per line, with the line placed inside an argument
printfx 'a.txt\nb.txt\n' | xargsx -I {} cpx {} {}.bakTreat each line as one item, blanks and quotes included
xargsx -d '\n' -a names.txt touchxPrint each command line before it runs
seqx 4 | xargsx -t -n 2 echoxAsk before each removal (the answer is read from the terminal)
lsx | xargsx -p -n 1 rmxChecksum many files four commands at a time
findx . -type f -print0 | xargsx -0 -n 50 -P 4 sha256sumxUse one input line per command, as -L counts them
printfx 'a b\nc d\n' | xargsx -L 1 echox line:Stop reading at a marker item
printfx 'a b END c\n' | xargsx -E END echoxKeep every command line within 20 bytes
seqx 10 | xargsx -s 20 echoxRun a program from PATH rather than the gnux tool of the same name
printfx 'a b\n' | xargsx envx echoTell a failing command (status 123) from a missing one (127)
echox x | xargsx no-such-command; echox "status: $?"Show the size limits in effect without running anything
xargsx --show-limits -r < /dev/nullOptions
Each option has a page of its own, with its usage and examples.
- -a, --arg-file: Read arguments from FILE, not standard input.
- -d, --delimiter: Items in the input are separated by CHARACTER, not by whitespace; disables quote and backslash processing and logical EOF processing.
- -e, --eof: Equivalent to
-EEND if END is specified; otherwise, there is no end-of-file string. - -E, --eof-string: Set logical EOF string to END; if END occurs as an item of input,
the rest of the input is ignored (ignored if -0 or
-dwas specified). - -x, --exit: Exit if the size (see
-s) is exceeded. - -p, --interactive: Prompt before running commands.
- -n, --max-args: Use at most MAX-ARGS arguments per command line.
- -s, --max-chars: Limit length of command line to MAX-CHARS.
- -L, --max-input-lines: Use at most MAX-LINES non-blank input lines per command line.
- -l, --max-lines: Similar to
-Lbut defaults to at most one non-blank input line if MAX-LINES is not specified. - -P, --max-procs: Run at most MAX-PROCS processes at a time.
- -r, --no-run-if-empty: If there are no arguments, then do not run COMMAND; if this option is not given, COMMAND will be run at least once.
- -0, --null: Items are separated by a NUL, not whitespace; disables quote and backslash processing and logical EOF processing.
- -o, --open-tty: Reopen stdin as /dev/
ttyin the child process before executing the command (not supported). - --process-slot-var: Set environment variable VAR in child processes (not supported).
- -i, --replace: Replace R in INITIAL-ARGS with names read from standard input,
splitat newlines; if R is unspecified, assume {}. - -I, --replace-string: Same as
--replace=R. - --show-limits: Show limits on command-line length.
- -t, --verbose: Print commands before executing them.
Exit status
| Status | Meaning |
|---|---|
| 0 | every command ran and exited with status 0 |
| 1 | xargsx itself failed: a bad option value, an unmatched quote, an argument line too long, an input file it could not open |
| 123 | a command exited with a status from 1 to 254 (the remaining commands still ran) |
| 124 | a command exited with status 255; no further command was started |
| 125 | a signal ended a command; no further command was started |
| 126 | the command was found but could not be run |
| 127 | the command was not found |
Help in the terminal
xargsx --help # options, first examples, exit status
gnux help xargsx # this page: the full manual
gnux help xargsx --OPTION # one option in depth, with its examples