Bash – Usage of enclosing braces {} as arguments to commands and their options

bashshell

Examples

I've recently found examples of using pairs of enclosing braces {}, with nothing in between the opening and closing braces, as arguments to commands and even to their options:

cat foo | xargs -I{} echo {}

find . -size 0 -exec rm -i {} \;

No Documentation

My problem is that I cannot find a documentation in the GNU Bash Manual that describes the usage of {} in such context as in the examples above.

I do not think it is a parameter expansion, because a dollar sign must precede the enclosing braces in a parameter expansion as in ${}.

It cannot be a brace expansion either, because it takes the form of {x..y[..incr]}, where x and y are not optional.

It also cannot be a command grouping either, because {} is used as arguments.

Questions

What does a pair of enclosing braces {} even mean, in general, as an argument to any command that accepts it?
Where can I find a documentation that describes the usage of {} as arguments?

Best Answer

These curly braces are left alone by bash; they belong to find and xargs, respectively, and are described in their man-pages.

`man find`

-exec command ;

Execute command; true if 0 status is returned. All following arguments to find are taken to be arguments to the command until an argument consisting of ; is encountered. The string {} is replaced by the current file name being processed everywhere it occurs in the arguments to the command, not just in arguments where it is alone, as in some versions of find. Both of these constructions might need to be escaped (with a \) or quoted to protect them from expansion by the shell. See the EXAMPLES section for examples of the use of the -exec option. The specified command is run once for each matched file. The command is executed in the starting directory. There are unavoidable security problems surrounding use of the -exec action; you should use the -execdir option instead.

-exec command {} +

This variant of the -exec action runs the specified command on the selected files, but the command line is built by appending each selected file name at the end; the total number of invocations of the command will be much less than the number of matched files. The command line is built in much the same way that xargs builds its command lines. Only one instance of {} is allowed within the command. The command is executed in the starting directory. If find encounters an error, this can sometimes cause an immediate exit, so some pending commands may not be run at all. This variant of -exec always returns true.

-execdir command ;

-execdir command {} +

Like -exec, but the specified command is run from the subdirectory containing the matched file, which is not normally the directory in which you started find. This a much more secure method for invoking commands, as it avoids race conditions during resolution of the paths to the matched files. As with the -exec action, the + form of -execdir will build a command line to process more than one matched file, but any given invocation of command will only list files that exist in the same subdirectory. If you use this option, you must ensure that your $PATH environment variable does not reference .; otherwise, an attacker can run any commands they like by leaving an appropriately-named file in a directory in which you will run -execdir. The same applies to having entries in $PATH which are empty or which are not absolute directory names. If find encounters an error, this can sometimes cause an immediate exit, so some pending commands may not be run at all. The result of the action depends on whether the + or the ; variant is being used; -execdir command {} + always returns true, while -execdir command {} ; returns true only if command returns 0.

`man xargs`

-I replace-str

Replace occurrences of replace-str in the initial-arguments with names read from standard input. Also, unquoted blanks do not terminate input items; instead the separator is the newline character. Implies -x and -L 1.

-i[replace-str], --replace[=replace-str]

This option is a synonym for -Ireplace-str if replace-str is specified. If the replace-str argument is missing, the effect is the same as -I{}. This option is deprecated; use -I instead.

Edit: and here WHY bash ignores those curly braces:

`man bash`

{ list; }

list is simply executed in the current shell environment. list must be terminated with a newline or semicolon. This is known as a group command. The return status is the exit status of list. Note that unlike the metacharacters ( and ), { and } are reserved words and must occur where a reserved word is permitted to be recognized. Since they do not cause a word break, they must be separated from list by whitespace or another shell metacharacter.

For emphasis: list must be terminated with a newline or semicolon.

Related Solutions

bash – Passing Braces as Arguments to Bash Function

When you run findinfiles {*.js,*.html,} {release,dev,} "span", here is what happens:

Bash parses quotes and splits the command into words: findinfiles, {*.js,*.html,} {release,dev,} span.
Bash expands the braces, resulting in the list of words findinfiles, *.js, *.html, release, dev, span.
Bash expands the wildcard patterns *.js and *.html to the list of matching file names. If no file name matches either pattern, it is left alone.
Bash looks up the name findinfiles, finds out that it's a function, and executes the function with the supplied parameters.

You can prevent the braces and wildcards from being expanded at the function call, but then the braces will appear literally in the arguments, which isn't particularly useful.

I suggest changing the format of your function call. Instead of using braces, use only commas, and manually split the arguments at commas inside the function.

findinfiles () {
  local patterns="$1" excludes="$2" pattern="$3"
  shift 3
  typeset -a cmd dirs
  if [[ $# -eq 0 ]]; then dirs=(.); else dirs=("$@"); fi
  cmd=(grep --color=auto -iRnHr)
  local IFS=,
  for x in $patterns; do
    cmd+=("--include=$x")
  done
  for x in $excludes; do
    cmd+=("--exclude-dir=$x")
  done
  "${cmd[@]}" "${dirs}"
}

Explanations:

Store the first three parameters in local variables. Any extra parameters are directories to search in.
Set dirs to the list of extra parameters. If there are none, use . (current directory) instead.
Set IFS to a comma. When a script contains an unquoted variable expansion like $patterns and $excludes above, the shell performs the following:
1. Replace the variable by its value.
2. Split the variable into separate words wherever it contains a character that is present in IFS. By default, IFS contains whitespace characters (space, tab and newline).
3. Treat each word as a wildcard pattern and expand it to the list of matching files. If there is no matching file, leave the pattern alone.
(To avoid these expansion steps, use double quotes around the variable substitution, as in patterns="$1" and so on in the script above.)
The function builds the command line to execute incrementally in the array variable cmd. At the end, the command is executed.

Alternatively, you could build on the following settings:

shopt -s extglob globstar
fif_excludes='release dev'
alias fif='grep --color=auto -inH $fif_excludes'

Run commands like

fif span **/*.@(js|html)

Explanations:

shopt -s extglob activates the @(js|html) form of wildcard pattern, which matches either js or html. (This option activates other pattern forms, see the manual for details.)
shopt -s globstar actives the pattern **/ which matches subdirectories at any depth (i.e. it performs a recursive traversal).
To change the exclude list (which I expect doesn't happen often), modify the fif_excludes variable.

Bash – Maintain filenames as separate arguments in successive commands

Hmm. @don_crissti already gave the answer for grep in a comment. But since you said it wasn't really about grep or ls, I'm going to rewrite the command in question to not use those commands.

What I think you want is:

do-something-with $(produce-list-of-files)

where the output of one command should be dropped in as command line parameters to another command. There just happens to be a utility just for that, it is called xargs (man page).

If the file names are "nice", we could do just

produce-list-of-files | xargs do-something-with

If the file names can contain spaces but are separated by newlines, we have to tell xargs to not split on any whitespace, but only newlines:

produce-list-of-files | xargs -d '\n' do-something-with

If the file names can contain newlines too, the list has to be separated by NULs ('\0', byte with value zero), and we need an xargs that supports it. At least some versions of various utilities support listing files separated by NULs instead of newlines, there's at least find -print0, sort -z and grep -Z in the GNU versions of those tools. In xargs the flag is --null or -0. So:

produce-list-of-files -0 | xargs -0 do-something-with

An example run with cat and, well, ls -l:

$ touch "abba acdc" "foo bar" $'new\nline'
$ echo -en "abba acdc\0foo bar\0new\nline\0" > list
$ cat list | xargs -0 ls -l
-rw-r--r-- 1 itvirta itvirta 0 Aug  2 01:23 abba acdc
-rw-r--r-- 1 itvirta itvirta 0 Aug  2 01:23 foo bar
-rw-r--r-- 1 itvirta itvirta 0 Aug  2 01:23 new?line

Bash – Usage of enclosing braces {} as arguments to commands and their options

Examples

No Documentation

Questions

Best Answer

`man find`

`-exec` command `;`

`-exec` command `{}` `+`

`-execdir` command `;`

`-execdir` command `{}` `+`

`man xargs`

`-I` replace-str

`-i`[replace-str], `--replace`[`=`replace-str]

`man bash`

`{` list`;` `}`

Related Question

Examples

No Documentation

Questions

Best Answer

man find

-exec command ;

-exec command {} +

-execdir command ;

-execdir command {} +

man xargs

-I replace-str

-i[replace-str], --replace[=replace-str]

man bash

{ list; }

Related Solutions

bash – Passing Braces as Arguments to Bash Function

Bash – Maintain filenames as separate arguments in successive commands

Related Question

`man find`

`-exec` command `;`

`-exec` command `{}` `+`

`-execdir` command `;`

`-execdir` command `{}` `+`

`man xargs`

`-I` replace-str

`-i`[replace-str], `--replace`[`=`replace-str]

`man bash`

`{` list`;` `}`