From cbddb63e1a27cd40f4c139ce27143ca81a547ceb Mon Sep 17 00:00:00 2001 From: Christian Neukirchen Date: Sat, 24 Oct 2015 17:53:12 +0200 Subject: initial import of xa --- README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..20aab72 --- /dev/null +++ b/README.md @@ -0,0 +1,68 @@ +## xa: simple xargs and apply replacement + +`xa` is a new tool for constructing command lines from file listings +or arguments, which includes the best features of `xargs(1)` and +`apply(1)`. + +## Benefits + +Over xargs: +* Sane defaults (behaves like `xargs -d'\n' -I{} -L1 -n1 -r`). +* No weird parsing, arguments are seperated linewise or by NUL byte. +* Can also take arguments from command-line. +* No shell involved unless `-s` is used. + +Over apply: +* Parallel mode. +* Sane argument splitting. +* Can use shell-syntax instead of escape characters. + +## Usage: + + xa [-0nv] [-I arg] [-N maxargs] [-j maxjobs] COMMAND... + | -s SHELLSCRIPT + | -a COMMAND... -- ARGS... + | -A ARGSEP COMMAND... ARGSEP ARGS... + +* `-0`: input filenames are seperated by NUL bytes (default: newlines). +* `-n`: don't run the commands, just print them. +* `-v`: print commands before running them. +* `-I`: replace occurences of *arg* with the argument (default: `{}`). +* `-N`: pass upto *maxargs* arguments to each COMMAND (default: 1). +* `-j`: run up to *maxjobs* processes concurrently. +* `COMMAND...`: default operation: each command line argument is + passed as-is, `{}` is replaced by the argument (not with `-N` > 1). +* `-s SHELLSCRIPT`: The argument `SHELLSCRIPT` is evaluated using `/bin/sh` + with the arguments (up to `-N`) passed as `$1`, `$2`, `$3`... + (this behaves as if `/bin/sh -c SHELLSCRIPT -` is passed as plain COMMAND). +* `-a`: take arguments from commandline, starting after the first `--`. +* `-A`: take arguments from commandline, starting after the first *argsep*. + +## Return code + +Like GNU and OpenBSD xargs: + +* 0 on success +* 123 if any invocation of the command exited with status 1-125 +* 124 if the command exited with status 255 +* 125 if the command is killed by a signal +* 126 if the command cannot be run +* 127 if the command is not found +* 1 if some other error occurred. + +## Installation + +Use `make all` to build, `make install` to install relative to `PREFIX` +(`/usr/local` by default). The `DESTDIR` convention is respected. +You can also just copy the binary into your `PATH`. + +## Copyright + +xa is in the public domain. + +To the extent possible under law, +Christian Neukirchen +has waived all copyright and related or +neighboring rights to this work. + +http://creativecommons.org/publicdomain/zero/1.0/ -- cgit 1.4.1