DECORATE(1)

NAME
decorate - convert fields of various formats

SYNOPSIS
decorate [OPTION]... [INPUT]
decorate --decorate [OPTION]... [INPUT]
decorate --undecorate N [OPTION]... [INPUT]

DESCRIPTION
Converts (and optionally sorts) fields of various formats

With --decorate: adds the converted fields to the start of each line and prints and prints it to STDOUT; does not sort.

With --undecorate: removes the first N fields from the input; Use as post-processing step after sort(1).

Without --decorate and --undecorate: automatically decorates the input, runs sort(1) and undecorates the result; This is the easiest method to use. The decorate program allows sorting input according to various ordering, e.g. IP addresses, roman numerals, etc. It works in tandem with sort(1) to perform the actual sorting.

The idea was suggested by Pádraig Brady in https://lists.gnu.org/r/bug-coreutils/2015-06/msg00076.html:

1. Decorate: convert the input to a sortable-format as additional fields
2. Sort according to the inserted fields
3. Undecorate: remove the inserted fields

OPTIONS

  General Options:

--decorate
    decorate/convert the specified fields and print the output to STDOUT. Does not automatically run sort(1) or undecorates the output

--header=N
    does not decorate or sort the first N lines

-H  same as --header=N

-k, --key=KEYDEF
    key/field to sort; same syntax as sort(1), optionally followed by ':method' to convert to the field into a sortable value; see examples and available conversion below

-t, --field-separator=SEP
    use SEP instead of non-blank to blank transition

--print-sort-args
    print adjusted parameters for sort(1); Useful when using --decorate and then manually running sort(1)

--undecorate=N
    removes the first N fields

-z, --zero-terminated
    line delimiter is NUL, not newline

--sort-cmd=/path/to/sort
    Alternative sort(1) to use.

-h, --help
    display this help and exit

-V, --version
    output version information and exit

The following options are passed to sort as-is (Most of them assume GNU sort):

-c, --check

--compress-program

--random-source

-s, --stable

--batch-size

-S, --buffer-size

-T, --temporary-directory

-u, --unique

--parallel

Available conversions methods (use with -k):

as-is
    copy as-is

roman
    roman numerals

strlen
    length (in bytes) of the specified field

ipv4
    dotted-decimal IPv4 addresses

ipv6
    IPv6 addresses

ipv4inet
    number-and-dots IPv4 addresses (incl. octal, hex values)

ipv6v4map
    IPv6 and IPv4 (as IPv4-Mapped IPv6) addresses

ipv6v4comp
    IPv6 and IPv4 (as IPv4-Compatible IPv6) addresses

EXAMPLES
Example of preparing to sort by roman numerals:

    $ printf "%s\n" C V III IX XI | decorate -k1,1:roman --decorate
    0000100 C
    0000005 V
    0000003 III
    0000009 IX
    0000011 XI

The output can now be sent to sort(1), followed by removing (=undecorate) the first field.

    $ printf "%s\n" C V III IX XI \
           | decorate -k1,1:roman --decorate \
           | sort -k1,1 \
           | decorate --undecorate 1
    III
    V
    IX
    XI
    C

decorate(1) can automatically combine the decorate-sort-undecorate steps (when run without --decorate or --undecorate):

    $ printf "%s\n" C V III IX XI | decorate -k1,1:roman
    III
    V
    IX
    XI
    C

ADDITIONAL INFORMATION
See GNU Datamash Website (https://www.gnu.org/software/datamash)

AUTHOR
Written by Assaf Gordon, Timothy Rice, Shawn Wagner and Erik Auerswald.

COPYRIGHT
Copyright © 2025 Assaf Gordon and Timothy Rice License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

SEE ALSO
The full documentation for decorate is maintained as a Texinfo manual. If the info and decorate programs are properly installed at your site, the command

    info decorate

should give you access to the complete manual.