Skip to Content
gnux

headx

Print the first part of each file.

Mirrors GNU head. Run it as headx, or as gnux headx.

Synopsis

headx [OPTION]... [FILE]...

GNU reference

Description

headx prints the first 10 lines of each FILE to standard output. With no FILE, or when FILE is -, it reads standard input. -n NUM changes the number of lines and -c NUM switches to bytes; a leading '-' on NUM inverts the selection and prints everything except the last NUM lines or bytes. NUM accepts a multiplier suffix: b is 512, K, M, G, T, P and E are powers of 1024 (also written KiB, MiB, ...), and KB, MB, ... are powers of 1000. With more than one FILE each is preceded by a '==> name <==' header; -q suppresses the headers and -v forces them. -z makes NUL the line delimiter. The historical 'headx -NUM' spelling of '-n NUM' is accepted. Reading stops as soon as enough has been seen, so headx is cheap on huge files. On a terminal, gnux's terminal view colors the '==> FILE <==' headers in the theme's heading color; the text is GNU's, and piped or redirected output is never colored.

Permissions

Needs read permission on each FILE and search permission on the directories leading to it. Nothing is ever modified.

Use cases

  • Peeking at the start of a large file or log without reading all of it.
  • Taking the first few results of a pipeline.
  • Dropping a fixed-size trailer with -n -NUM or -c -NUM.
  • Sampling the first bytes of a binary file with -c, for example to check a magic number.
  • Reading the header row of a CSV file before processing it.
  • Comparing the beginnings of several files side by side, with or without '==> name <==' headers.
  • Cutting an endless stream such as yesx down to a fixed number of lines.
  • Extracting a range of lines when combined with tailx.
  • Handling NUL-separated file lists safely with -z.

Flags

  -c, --bytes [-]NUM             print the first NUM bytes of each file; with a leading '-', print all but the last NUM bytes of each file
      --help                     display this help and exit
  -n, --lines [-]NUM             print the first NUM lines instead of the first 10; with a leading '-', print all but the last NUM lines of each file
      --pretty WHEN[="always"]   the gnux terminal view WHEN: 'always' (the default when WHEN is omitted), 'auto' (the default: on a terminal only), or 'never'; GNUX_PRETTY sets the default
  -q, --quiet                    never print headers giving file names
      --silent                   same as --quiet
      --theme NAME               color the view with the built-in theme NAME (gnux theme picks and saves one); GNUX_THEME sets the default
  -v, --verbose                  always print headers giving file names
      --version                  output version information and exit
  -z, --zero-terminated          line delimiter is NUL, not newline

Examples

headx access.log
headx -n 3 a.txt b.txt
headx -n 1 data.csv
headx -q -n 1 *.csv

Show the file name header even for a single file (--silent is the long spelling of -q)

headx -v -n 2 config.ini
headx -c 1K image.png > start.bin

Check a file's magic number from its first bytes

headx -c 4 image.png | catx -v

Copy the first megabyte (10^6 bytes) of a large file

headx -c 1MB disk.img > sample.img
headx -n -2 report.txt

Strip the final byte, such as a trailing newline

headx -c -1 version.txt

Keep the first 5 lines of a pipeline, using the historical -NUM form

lsx -t | headx -5
headx -n 20 app.log | tailx -n 10

Cut an endless stream down to three lines

yesx ok | headx -n 3

Take the first two entries of a NUL-separated list

find . -name '*.txt' -print0 | headx -z -n 2 | xargs -0 wcx -l

Fail a script when a file cannot be read

headx -n 1 missing.txt || echox "exit status $?"

Preview the start of every log in the portable gnux shell

gnux shell -c 'headx -n 3 *.log'

Options

Each option has a page of its own, with its usage and examples.

  • -c, --bytes: Print the first NUM bytes of each file; with a leading '-', print all but the last NUM bytes of each file.
  • -n, --lines: Print the first NUM lines instead of the first 10; with a leading '-', print all but the last NUM lines of each file.
  • --pretty: The gnux terminal view WHEN: 'always' (the default when WHEN is omitted), 'auto' (the default: on a terminal only), or 'never'; GNUX_PRETTY sets the default.
  • -q, --quiet: Never print headers giving file names.
  • --silent: Same as --quiet.
  • --theme: Color the view with the built-in theme NAME (gnux theme picks and saves one); GNUX_THEME sets the default.
  • -v, --verbose: Always print headers giving file names.
  • -z, --zero-terminated: Line delimiter is NUL, not newline.

Exit status

StatusMeaning
0success: every operand was processed
1failure: an operand could not be processed (diagnosed on standard error), or a command-line mistake

Help in the terminal

headx --help                # options, first examples, exit status
gnux help headx             # this page: the full manual
gnux help headx --OPTION    # one option in depth, with its examples

See also

On this page