Formatted Terminal Output with `fmt` and `text/tabwriter`

1. The fmt Package: Your Formatting Workhorse

The fmt package is one of the first packages you encounter in Go, and for good reason. It's the standard library's solution for formatted I/O. While you've likely used fmt.Println already, the package offers much more control.

The functions in fmt generally come in three families:

• Print...: Writes to standard output (os.Stdout).
• Fprint...: Writes to a specified io.Writer. This is incredibly useful for directing output to files, network connections, or, as we'll see, standard error (os.Stderr).
• Sprint...: Formats data into a string variable in memory, without printing it.

Fine-Grained Control with fmt.Printf

fmt.Printf is the key to precise formatting. It uses "format verbs" (placeholders like %s or %d) to control how data is represented in the output string.

The following video provides an excellent introduction to the fmt package, covering the differences between Println and Printf, and introducing the most common format verbs.

As you saw, verbs like %v, %T, and %+v are fantastic for debugging, while %s, %d, and %f give you control over production output.

Manual Alignment: Width and Precision

You can add numbers to format verbs to control width and padding. This is a first step towards creating aligned columns, though as we'll see, it has its limits.

• %10s: Pads a string with spaces on the left to be 10 characters wide.
• %-10s: Pads a string with spaces on the right (left-justifies it) to be 10 characters wide.
• %.2f: Formats a floating-point number with 2 decimal places of precision.
• %04d: Pads an integer with leading zeros to be 4 digits wide.

This next video provides a hands-on demonstration of these features.

Let's try a quick example. Imagine printing a list of running services:

package main

import "fmt"

func main() {
    fmt.Printf("%-15s %-10s %5s\n", "SERVICE", "STATUS", "PORT")
    fmt.Printf("%-15s %-10s %5d\n", "api-gateway", "Running", 8080)
    fmt.Printf("%-15s %-10s %5d\n", "user-database", "Running", 5432)
    fmt.Printf("%-15s %-10s %5d\n", "auth-service", "Failed", 8081)
}

This produces a nicely aligned table:

SERVICE         STATUS     PORT
api-gateway     Running     8080
user-database   Running     5432
auth-service    Failed      8081

However, this manual approach is brittle. If a service name were longer than 15 characters, the alignment would break. For robust, dynamic tables, we need a better tool.

2. Professional Tables with text/tabwriter

Go's standard library provides the text/tabwriter package to solve the problem of column alignment once and for all. It works by acting as a filter: you write tab-delimited text to it, and it automatically calculates the required padding to make all columns align perfectly.

The core workflow is simple:

1. Create a new tabwriter.Writer.
2. Write your content to it, using tab characters (\t) to separate columns and newlines (\n) to separate rows. You typically use fmt.Fprintf for this.
3. Flush the writer to produce the final, formatted output on its destination io.Writer.

The following article is a fantastic guide to tabwriter. We'll work through it step-by-step.

Let's rewrite our previous service list example using tabwriter:

package main

import (
	"fmt"
	"os"
	"text/tabwriter"
)

func main() {
	// 1. Create a new tabwriter that writes to os.Stdout
	w := tabwriter.NewWriter(os.Stdout, 0, 0, 3, ' ', 0) // minwidth, tabwidth, padding, padchar, flags

	// 2. Write tab-separated values
	fmt.Fprintln(w, "SERVICE\tSTATUS\tPORT")
	fmt.Fprintln(w, "api-gateway\tRunning\t8080")
	fmt.Fprintln(w, "user-database-with-a-very-long-name\tRunning\t5432") // Alignment holds!
	fmt.Fprintln(w, "auth-service\tFailed\t8081")

	// 3. Flush the writer to print the formatted output
	w.Flush()
}

Output:

SERVICE                                  STATUS    PORT
api-gateway                              Running   8080
user-database-with-a-very-long-name      Running   5432
auth-service                             Failed    8081

Notice how tabwriter automatically handled the long service name, keeping all columns aligned.

Configuring tabwriter

You can customize the output by changing the parameters in tabwriter.NewWriter. The most important ones are minwidth, padding, and flags.

A common and robust pattern is to use defer to ensure Flush() is always called.

func printTable() {
    w := tabwriter.NewWriter(os.Stdout, 0, 0, 3, ' ', 0)
    defer w.Flush() // Guarantees the buffer is flushed before the function returns.

    fmt.Fprintln(w, "ID\tNAME\tSTATUS")
    fmt.Fprintln(w, "1\tnginx\tRunning")
    fmt.Fprintln(w, "2\tpostgres\tRunning")
}

package main

import (
	"fmt"
	"os"
	"text/tabwriter"
)

func main() {
	// Use the AlignRight flag
	w := tabwriter.NewWriter(os.Stdout, 0, 0, 3, ' ', tabwriter.AlignRight)
	defer w.Flush()

	fmt.Fprintln(w, "SERVICE\tSTATUS\tPORT")
	fmt.Fprintln(w, "api-gateway\tRunning\t8080")
	fmt.Fprintln(w, "user-database-with-a-very-long-name\tRunning\t5432")
	fmt.Fprintln(w, "auth-service\tFailed\t8081")
}

                              SERVICE      STATUS   PORT
                          api-gateway     Running   8080
user-database-with-a-very-long-name     Running   5432
                         auth-service      Failed   8081

3. Putting It All Together: A Reusable Table Printer

For larger applications, you'll want to encapsulate the tabwriter logic into a reusable helper function. This separates your data-gathering logic from your presentation logic, leading to cleaner code.

The following resource presents a complete, practical example of creating a generic PrintTable function. This pattern is something you can directly adapt for your own projects.

This approach is powerful because the PrintTable function doesn't need to know anything about users or permissions. It only deals with strings, making it a truly generic and reusable component for any tabular data you need to display.

Conclusion

You've now added a crucial skill to your Go toolkit: creating professional terminal output. This ability to present data clearly is what separates a quick script from a polished, user-friendly tool.

Key Takeaways:

• Use fmt.Printf with format verbs (%s, %d, %v) for fine-grained control over string formatting.
• Use fmt.Sprintf when you need to format data into a string variable for later use.
• text/tabwriter is the standard and robust way to create column-aligned tables.
• The tabwriter workflow is: NewWriter, write tab-delimited content, and Flush.
• Always remember to call w.Flush(). Using defer w.Flush() right after creating the writer is a failsafe pattern.
• For complex applications, encapsulate tabwriter logic in a reusable helper function that separates data transformation from presentation.

Next Up

You now know how to parse arguments, interact with the OS, handle data formats like JSON/YAML, and produce clean, formatted output. You have all the pieces to build a complete and useful CLI tool. In our next lesson, we'll cover the final step in the development lifecycle: creating installable, cross-compiled binaries for different operating systems. This will allow you to easily distribute your new tools to colleagues and servers, regardless of their platform.