logo

utils-std

Collection of commonly available Unix tools git clone https://anongit.hacktivis.me/git/utils-std.git/

shuf.1 (1472B)

    

  1. .\" utils-std: Collection of commonly available Unix tools
  2. .\" Copyright 2017 Haelwenn (lanodan) Monnier <contact+utils@hacktivis.me>
  3. .\" SPDX-License-Identifier: MPL-2.0
  4. .Dd October 31, 2025
  5. .Dt SHUF 1
  6. .Os
  7. .Sh NAME
  8. .Nm shuf
  9. .Nd print contents shuffled
  10. .Sh SYNOPSIS
  11. .Nm
  12. .Op Fl z
  13. .Op Fl n Ar num
  14. .Op Ar file...
  15. .Nm
  16. .Fl e
  17. .Op Fl z
  18. .Op Fl n Ar num
  19. .Op Ar string...
  20. .Sh DESCRIPTION
  21. In it's first form,
  22. .Nm
  23. reads lines from each
  24. .Ar file
  25. or if unspecified or when
  26. .Ar file
  27. is
  28. .Qq - ,
  29. lines are read from standard input.
  30. And are then shuffled and printed using a reservoir shuffle, see
  31. .Sx SHUFFLING
  32. for details.
  33. .Pp
  34. In it's second form,
  35. .Nm
  36. uses a Fisher-Yates shuffle to swap-shuffle all the strings,
  37. and then prints them out as lines.
  38. .Sh OPTIONS
  39. .Bl -tag -width _n_num
  40. .It Fl e
  41. Use each
  42. .Ar string
  43. as an input line.
  44. .It Fl n Ar num
  45. Output at most
  46. .Ar num
  47. lines.
  48. .It Fl z
  49. Use NULL as line delimiter, not newline.
  50. .El
  51. .Sh SHUFFLING
  52. In it's first form,
  53. .Nm
  54. .\" LINES_LEN
  55. uses a reservoir of 512 lines.
  56. It picks a random location,
  57. prints a line if present,
  58. then inserts a newly read line.
  59. Once all lines are read it prints the lines still present in the reservoir.
  60. .br
  61. While this isn't truly a random sort as lines beyond 512 won't be printed first,
  62. it allows to use a bounded amount of memory.
  63. .Sh EXIT STATUS
  64. .Ex -std
  65. .Sh SEE ALSO
  66. .Xr sort 1
  67. .Sh HISTORY
  68. An
  69. .Nm
  70. utility appeared in GNU coreutils 6.0.
  71. .Sh AUTHORS
  72. .An Haelwenn (lanodan) Monnier Aq Mt contact+utils@hacktivis.me