Linux / Comando xargs: transformar entrada em argumentos

xargs lê itens da entrada padrão e os acrescenta como argumentos de outro comando. Use-o quando uma lista produzida por um pipe deve virar, por exemplo, nomes de arquivos na linha de comando. Para preservar nomes com espaços, aspas ou quebras de linha, combine um produtor com separadores NUL, como find -print0, com xargs -0.

Um pipe comum entrega dados à entrada padrão do próximo programa; xargs constrói sua lista de argumentos e pode executá-lo várias vezes. Os argumentos fixos vêm antes dos itens lidos. O modo padrão separa itens por espaços e quebras de linha e interpreta aspas e barras invertidas, por isso uma lista de nomes não pode ser tratada como texto comum sem considerar esses caracteres.

Sintaxe e escolha da implementação

comando-gerador | xargs [opção...] comando [argumento-fixo...]

Essa linha descreve a sintaxe, não um comando pronto para executar. Substitua os marcadores pelo produtor, pelo comando de destino e por seus argumentos fixos. Confira xargs --version, xargs --help ou man xargs; os exemplos abaixo usam GNU xargs. Verifique o comportamento de entrada vazia e as opções na implementação do seu sistema.

NUL é o byte de valor zero usado aqui para marcar o fim de cada item. Com -0, espaços, aspas e barras invertidas passam a fazer parte literal dos itens, em vez de atuar como separadores ou regras de escape. O produtor também precisa emitir NUL: trocar apenas xargs por xargs -0 não corrige uma lista que ainda usa quebras de linha como separador.

Criar arquivos e observar os limites dos argumentos

Execute o bloco inteiro no Bash, dentro de uma pasta onde possa criar arquivos. Ele cria um diretório exclusivo, com dois arquivos de prática em reports, e trabalha em um subshell entre parênteses. set -euo pipefail faz este bloco simples parar após falhas, incluindo falhas anteriores no pipeline, e após uso de variáveis não definidas. A sessão retorna ao diretório anterior quando o subshell termina.

(
set -euo pipefail
labdir=$(mktemp -d ./xargs-demo.XXXXXX)
cd "$labdir"
mkdir reports
printf 'first\nsecond\n' > 'reports/two words.txt'
printf 'third\n' > 'reports/plain.txt'
printf '%s\0' 'reports/two words.txt' 'reports/plain.txt' |
    xargs -0 -r -n 1 printf 'ARG=[%s]\n'
find reports -type f -name '*.txt' -print0 | xargs -0 -r wc -l
printf 'two words\n' | xargs -n 1 printf 'SPLIT=[%s]\n'
printf 'Arquivos do laboratório: %s\n' "$PWD"
)

As duas primeiras linhas são ARG=[reports/two words.txt] e ARG=[reports/plain.txt]. Cada caminho ocupa um argumento, apesar do espaço no primeiro nome. O comando wc informa 2 linhas para two words.txt, 1 para plain.txt e total 3. A ordem dos arquivos nessa parte pode variar conforme a busca feita por find.

Depois aparecem SPLIT=[two] e SPLIT=[words]: sem -0, o texto two words foi dividido em dois itens. A última linha mostra o caminho completo da pasta de prática. Para os exemplos seguintes, entre nesse caminho com cd e coloque o caminho entre aspas.

O bloco foi conferido com GNU xargs e find 4.10.0 no Bash do Git para Windows, usando os dois arquivos locais, um deles com espaço no nome. Os exemplos seguintes usam apenas leitura ou exibição de argumentos; os arquivos de entrada permanecem disponíveis.

Entender entrada vazia e o tamanho dos lotes

No GNU xargs, a execução padrão ocorre uma vez mesmo sem itens. Para observar sem alterar arquivos, printf '' | xargs printf 'EXECUTOU\n' mostra EXECUTOU. Com printf '' | xargs -r printf 'EXECUTOU\n', o comando não é executado e não há saída. -r controla a execução com entrada vazia; não valida nomes nem garante que os itens existam.

-n N limita a quantidade de itens acrescentados por execução. Por exemplo, printf 'a b c\n' | xargs -n 2 printf 'PAR=[%s,%s]\n' mostra PAR=[a,b] e PAR=[c,]. O último lote tem apenas um item; a posição vazia vem do segundo marcador de printf, não de um item vazio fornecido por xargs.

O limite é um máximo, e o tamanho permitido para a linha de comando também pode forçar lotes menores. No exemplo original, os dois arquivos cabem em uma execução de wc, por isso há um total 3. Em listas grandes divididas em vários lotes, os totais de wc podem ser por execução, não um total único de toda a lista.

Substituir um marcador com -I

Para colocar cada item em uma posição específica, use um marcador como {}. O comando printf '%s\0' 'reports/two words.txt' 'reports/plain.txt' | xargs -0 -r -I '{}' printf 'arquivo=%s\n' '{}' mostra cada um dos dois caminhos inteiro em uma linha, precedido de arquivo=.

Esse uso mantém cada nome como dado passado a printf. Por padrão, xargs executa o comando diretamente, sem montar um programa de shell. Se você invocar explicitamente sh -c, não insira nomes recebidos dentro do texto do programa: caracteres do nome podem passar a ter significado de código. Passe dados como argumentos e use as regras de aspas do shell.

Sem -0, -I passa a ler por linhas, e espaços não protegidos deixam de terminar o item; isso ainda não preserva um nome que contenha uma quebra de linha. Além disso, -I processa um item por execução nesse uso e impõe um limite de tamanho. Não o combine indiscriminadamente com -n ou -L; confira as regras e avisos da implementação.

Distinguir nome de arquivo de opção do comando

-0 preserva os limites dos itens, mas o comando chamado ainda interpreta seus próprios argumentos. Se um nome começar com hífen, ele pode parecer uma opção. Para GNU wc, coloque -- antes dos nomes: find reports -type f -name '*.txt' -print0 | xargs -0 -r wc -l --. Aqui -- pertence a wc, pois vem depois do nome desse comando.

No bloco inicial, os caminhos começam com reports/, então não começam com hífen. Em outros fluxos, verifique os caminhos e o suporte a -- da ferramenta chamada. O fim das opções de xargs e o fim das opções do comando de destino são coisas diferentes.

Usar paralelismo somente quando as tarefas forem independentes

-P N permite até N processos de destino simultâneos. Combine-o com um tamanho de lote adequado, como -n 1, se quiser uma tarefa por item. Sem dividir a entrada, pode haver apenas uma execução, mesmo com -P maior que 1.

Você pode observar com printf '%s\0' um dois | xargs -0 -r -n 1 -P 2 printf 'ITEM=%s\n'. As mensagens ITEM=um e ITEM=dois não têm ordem garantida. Em trabalhos maiores, a saída de processos diferentes também pode se misturar; use destinos separados ou coordenação quando for necessário preservar resultados e evitar concorrência sobre o mesmo arquivo.

Conferir falhas e limites da segurança dos nomes

Antes de ligar um comando que altere ou remova arquivos, confira os itens com printf, explicado no guia em inglês, como no bloco de prática. A sequência find -print0 com xargs -0 evita a separação incorreta dos nomes, mas não congela o sistema de arquivos entre a busca e o uso. Em diretórios que outras pessoas podem alterar, um caminho pode mudar nesse intervalo.

Para operações originadas em find, avalie também find -exec ou -execdir conforme o comando, o diretório de execução e a necessidade de proteção contra mudanças no caminho. Confira sempre o alcance da busca antes de substituir a exibição de argumentos por uma ação que modifica dados.

Confira o término de xargs com echo "$?" imediatamente após a execução. No GNU xargs, falhas do comando chamado podem produzir um status diferente do status original: uma execução que termine com 1 normalmente faz xargs retornar 123. Erros de formação dos argumentos e comando não encontrado também devem ser tratados como falha. Algumas tarefas anteriores podem já ter sido executadas; não suponha que uma falha desfez seus efeitos.

Opções principais

Pergunta frequente

Qual é a diferença entre usar um pipe e usar xargs?

O pipe entrega dados à entrada padrão do próximo programa. xargs lê esses dados, separa os itens conforme seu modo e os coloca como argumentos de um comando. A escolha depende de como o programa de destino recebe os dados; para listas de nomes, confira também o delimitador e a interpretação de opções.

Documentação

Consulte a página de manual do GNU xargs publicada pelo Debian para delimitadores, entrada vazia, lotes, paralelismo, status de saída e limites de processamento de nomes.