Next: , Previous: sort invocation, Up: Operating on sorted files


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 lines’
‘--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.
‘-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:

     4
     2
     1
     3

These 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.

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