Getting started

progress-go draws a progress bar for a known amount of work. It has one type, Bar, and three calls:

• Start starts the clock and, on a terminal, draws the bar and keeps redrawing it.
• Advance adds to the work done, from any goroutine.
• Stop draws the bar one last time, ends its line, and returns any error from writing it.

Install

progress-go needs Go 1.26 or newer.

go get github.com/vardius/progress-go

Your first bar

This program does ten steps of a tenth of a second each, and advances a verbose bar after every step:

examples/count/main.go

// Command count counts to ten, a tenth of a second at a time, under a verbose bar.
//
//  go run ./examples/count
package main

import (
  "io"
  "log"
  "os"
  "time"

  "github.com/vardius/progress-go"
)

// count does n steps of work, each taking the given time, and advances the bar after each.
func count(out io.Writer, n int, each time.Duration) error {
  bar := progress.New(int64(n), progress.Options{Output: out, Verbose: true})
  bar.Start()
  for range n {
    time.Sleep(each) // a step of real work goes here
    bar.Advance(1)
  }
  return bar.Stop()
}

func main() {
  log.SetFlags(0)
  if err := count(os.Stdout, 10, 100*time.Millisecond); err != nil {
    log.Fatal(err)
  }
}

Run it

1. From a clone of the repository, run it in a terminal:

   go run ./examples/count

   The bar fills over a second, redrawn in place. Once it stops, the line reads:

   10/10 [██████████████████████████████████████████████████] 100% 176 KB 1s/1s 0s

   The heap size, 176 KB here, depends on your program.

2. Pipe it into another command. Its output is no longer a terminal, so the bar writes no escape codes and no frames along the way: only the last line, once.

   go run ./examples/count | cat

What just happened

• progress.New made a bar for 10 units of work. Options{Verbose: true} added the heap size and the times. With no Output, the bar draws to os.Stdout.
• Start started the clock. Standard output was a terminal, so it drew the bar and started a timer that redraws it every 100 ms.
• Each Advance(1) added one to the count and returned at once. The next redraw showed it.
• Stop stopped the timer, drew the bar a last time, and ended the line. It returns the first error from writing the bar, if there was one.

Next steps

Counting workItems, bytes, resuming part way, and work that overshoots.

OutputTerminals and logs, the glyph, verbose fields, write errors.

GoroutinesWorkers that share one bar, and what Advance costs.

BenchmarksWhat each call costs, and how v1 compares with the untagged version.