README.md
1# progressbar
2
3[](https://travis-ci.org/schollz/progressbar)
4[](https://goreportcard.com/report/github.com/schollz/progressbar)
5[](https://gocover.io/github.com/schollz/progressbar)
6[](https://godoc.org/github.com/schollz/progressbar)
7
8A very simple thread-safe progress bar which should work on every OS without problems. I needed a progressbar for [croc](https://github.com/schollz/croc) and everything I tried had problems, so I made another one. In order to be OS agnostic I do not plan to support [multi-line outputs](https://github.com/schollz/progressbar/issues/6).
9
10
11## Install
12
13```
14go get -u github.com/schollz/progressbar/v3
15```
16
17## Usage
18
19### Basic usage
20
21```golang
22bar := progressbar.Default(100)
23for i := 0; i < 100; i++ {
24 bar.Add(1)
25 time.Sleep(40 * time.Millisecond)
26}
27```
28
29which looks like:
30
31
32
33
34### I/O operations
35
36The `progressbar` implements an `io.Writer` so it can automatically detect the number of bytes written to a stream, so you can use it as a progressbar for an `io.Reader`.
37
38```golang
39req, _ := http.NewRequest("GET", "https://dl.google.com/go/go1.14.2.src.tar.gz", nil)
40resp, _ := http.DefaultClient.Do(req)
41defer resp.Body.Close()
42
43f, _ := os.OpenFile("go1.14.2.src.tar.gz", os.O_CREATE|os.O_WRONLY, 0644)
44defer f.Close()
45
46bar := progressbar.DefaultBytes(
47 resp.ContentLength,
48 "downloading",
49)
50io.Copy(io.MultiWriter(f, bar), resp.Body)
51```
52
53which looks like:
54
55
56
57
58### Progress bar with unknown length
59
60A progressbar with unknown length is a spinner. Any bar with -1 length will automatically convert it to a spinner with a customizable spinner type. For example, the above code can be run and set the `resp.ContentLength` to `-1`.
61
62which looks like:
63
64
65
66
67### Customization
68
69There is a lot of customization that you can do - change the writer, the color, the width, description, theme, etc. See [all the options](https://pkg.go.dev/github.com/schollz/progressbar/v3?tab=doc#Option).
70
71```golang
72bar := progressbar.NewOptions(1000,
73 progressbar.OptionSetWriter(ansi.NewAnsiStdout()),
74 progressbar.OptionEnableColorCodes(true),
75 progressbar.OptionShowBytes(true),
76 progressbar.OptionSetWidth(15),
77 progressbar.OptionSetDescription("[cyan][1/3][reset] Writing moshable file..."),
78 progressbar.OptionSetTheme(progressbar.Theme{
79 Saucer: "[green]=[reset]",
80 SaucerHead: "[green]>[reset]",
81 SaucerPadding: " ",
82 BarStart: "[",
83 BarEnd: "]",
84 }))
85for i := 0; i < 1000; i++ {
86 bar.Add(1)
87 time.Sleep(5 * time.Millisecond)
88}
89```
90
91which looks like:
92
93
94
95
96## Contributing
97
98Pull requests are welcome. Feel free to...
99
100- Revise documentation
101- Add new features
102- Fix bugs
103- Suggest improvements
104
105## Thanks
106
107Thanks [@Dynom](https://github.com/dynom) for massive improvements in version 2.0!
108
109Thanks [@CrushedPixel](https://github.com/CrushedPixel) for adding descriptions and color code support!
110
111Thanks [@MrMe42](https://github.com/MrMe42) for adding some minor features!
112
113Thanks [@tehstun](https://github.com/tehstun) for some great PRs!
114
115Thanks [@Benzammour](https://github.com/Benzammour) and [@haseth](https://github.com/haseth) for helping create v3!
116
117Thanks [@briandowns](https://github.com/briandowns) for compiling the list of spinners.
118
119## License
120
121MIT
122
){kind=link}
){kind=link}
){kind=link}
