The ‘keep-header’ command is a powerful tool in the tsv-utils package that allows users to manipulate files while keeping the first line intact. It is especially useful when working with datasets or files that have a header row that you want to preserve.

Use case 1: Sort a file and keep the first line at the top

Code:

keep-header path/to/file -- sort

Motivation: Sorting a file is a common operation, but it often results in the loss of the header row. By using the ‘keep-header’ command, we can ensure that the header row remains at the top of the sorted file.

Explanation: The ‘keep-header’ command reads the input file specified by ‘path/to/file’. It then passes the first line directly to the standard output (‘stdout’) while sorting the rest of the file using the ‘sort’ command.

Example Output:

Header1,Header2,Header3
data1,data2,data3
data4,data5,data6
data7,data8,data9

Use case 2: Output first line directly to stdout, passing the remainder of the file through the specified command

Code:

keep-header path/to/file -- command

Motivation: There may be instances where you want to process the file in a specific way, but only after examining the header row. By using the ‘keep-header’ command with a custom command, you can easily achieve this.

Explanation: In this use case, the ‘keep-header’ command reads the input file specified by ‘path/to/file’. It then passes the first line directly to the standard output (‘stdout’) and the rest of the file through the specified command.

Example Output:

Header1,Header2,Header3
Processed data1
Processed data2
Processed data3

Use case 3: Read from stdin, sorting all except the first line

Code:

cat path/to/file | keep-header -- sort

Motivation: This use case is similar to the first one, but it allows users to read from stdin instead of specifying an input file directly. This can be useful in cases where the file is being piped from another command.

Explanation: The ‘cat’ command is used to read the contents of the file specified by ‘path/to/file’ and pass it to ‘stdin’. The ‘keep-header’ command then reads from stdin, passing the first line directly to ‘stdout’ and sorting the rest of the file using the ‘sort’ command.

Example Output:

Header1,Header2,Header3
data4,data5,data6
data7,data8,data9
data1,data2,data3

Use case 4: Grep a file, keeping the first line regardless of the search pattern

Code:

keep-header path/to/file -- grep pattern

Motivation: When using the ‘grep’ command to filter a file based on a pattern, the header row is typically not matched, resulting in its omission in the output. By using the ‘keep-header’ command, we can guarantee that the header row is always included in the grep output.

Explanation: The ‘keep-header’ command reads the input file specified by ‘path/to/file’. It then passes the first line directly to ‘stdout’ and applies the ‘grep’ command to the remainder of the file using the specified ‘pattern’.

Example Output:

Header1,Header2,Header3
data1,1234,data3

Conclusion:

The ‘keep-header’ command is a versatile tool that allows users to manipulate files while keeping the first line intact. Whether you need to sort a file, apply a custom command, or grep a file, the ‘keep-header’ command provides the flexibility to achieve these tasks without sacrificing the header row.