shuf

2 min read

shuf shuffles: it outputs its input lines in a random order. Every possible ordering is equally likely.

shuf [options] [file]
shuf -e [options] arg...
shuf -i lo-hi [options]

$ shuf playlist.txt

shuf is the opposite of sort — instead of imposing an order, it removes one. With no file, it reads standard input.

Where the lines come from #

shuf has three ways of getting its input, one per usage form:

Option	Input is…
(a file, or stdin)	the lines of the file.
`-e`, `--echo`	the command-line arguments, each treated as one line.
`-i`, `--input-range=LO-HI`	the integers from `LO` to `HI`, each treated as one line.

$ shuf -e red green blue          # shuffle three given words
$ shuf -i 1-100                   # the numbers 1..100 in random order

Option	Effect
`-n`, `--head-count=COUNT`	Output at most `COUNT` lines — a random sample rather than the whole shuffle.
`-r`, `--repeat`	Allow lines to be repeated, so output can be longer than the input. Pair with `-n` to set how many.
`-o`, `--output=FILE`	Write to `FILE` instead of standard output.
`-z`, `--zero-terminated`	Treat the NUL character as the line delimiter.

shuf -n 1 is a common idiom — pick one random line.

A shuffle is random by default. To get the same shuffle every time — for a repeatable test, say — fix the randomness:

Option	Effect
`--random-seed=STRING`	Seed the shuffle with `STRING`. The same seed gives the same shuffle.
`--random-source=FILE`	Take the random bytes from `FILE`. The same file gives the same shuffle. Cannot be combined with `--random-seed`.

Code	Meaning
`0`	Success.
`1`	A failure — the input could not be read, or `-r` was used with no lines to repeat.