shuf invocation (GNU Coreutils 9.0)

7.2 shuf: Shuffling text

shuf shuffles its input by outputting a random permutation of its input lines. Each output permutation is equally likely. Synopses:

shuf [option]… [file]
shuf -e [option]… [arg]…
shuf -i lo-hi [option]…

shuf has three modes of operation that affect where it obtains its input lines. By default, it reads lines from standard input. The following options change the operation mode:

‘-e’ ‘--echo’

Treat each command-line operand as an input line.

‘-i lo-hi’ ‘--input-range=lo-hi’

Act as if input came from a file containing the range of unsigned decimal integers lo…hi, one per line.

shuf’s other options can affect its behavior in all operation modes:

‘-n count’ ‘--head-count=count’

Output at most count lines. By default, all input lines are output.

‘-o output-file’ ‘--output=output-file’

Write output to output-file instead of standard output. shuf reads all input before opening output-file, so you can safely shuffle a file in place by using commands like shuf -o F <F and cat F | shuf -o F.

‘--random-source=file’

Use file as a source of random data used to determine which permutation to generate. See Random sources.

‘-r’ ‘--repeat’

Repeat output values, that is, select with replacement. With this option the output is not a permutation of the input; instead, each output line is randomly chosen from all the inputs. This option is typically combined with --head-count; if --head-count is not given, shuf repeats indefinitely.

‘-z’ ‘--zero-terminated’

Delimit items with a zero byte rather than a newline (ASCII LF). I.e., treat input as items separated by ASCII NUL and terminate output items with ASCII NUL. This option can be useful in conjunction with ‘perl -0’ or ‘find -print0’ and ‘xargs -0’ which do the same in order to reliably handle arbitrary file names (even those containing blanks or other special characters).

For example:

shuf <<EOF
A man,
a plan,
a canal:
Panama!
EOF

might produce the output

Panama!
A man,
a canal:
a plan,

Similarly, the command:

shuf -e clubs hearts diamonds spades

might output:

clubs
diamonds
spades
hearts

and the command ‘shuf -i 1-4’ might output:

The above examples all have four input lines, so shuf might produce any of the twenty-four possible permutations of the input. In general, if there are n input lines, there are n! (i.e., n factorial, or n * (n - 1) * … * 1) possible output permutations.

To output 50 random numbers each in the range 0 through 9, use:

shuf -r -n 50 -i 0-9

To simulate 100 coin flips, use:

shuf -r -n 100 -e Head Tail

An exit status of zero indicates success, and a nonzero value indicates failure.