## 1. Project Overview & Quickstart (dundee/gdu)

## File: README.md

# go DiskUsage()



[](https://codecov.io/gh/dundee/gdu)
[](https://goreportcard.com/report/github.com/dundee/gdu)
[](https://codeclimate.com/github/dundee/gdu/maintainability)
[](https://codescene.io/projects/13129)

Pretty fast disk usage analyzer written in Go.

Gdu is intended primarily for SSD disks where it can fully utilize parallel processing.
However HDDs work as well, but the performance gain is not so huge.

[](https://asciinema.org/a/382738)

<a href="https://repology.org/project/gdu/versions">
    
</a>

## Installation

Head for the [releases page](https://github.com/dundee/gdu/releases) and download the binary for your system.

Using curl:

    curl -L https://github.com/dundee/gdu/releases/latest/download/gdu_linux_amd64.tgz | tar xz
    chmod +x gdu_linux_amd64
    mv gdu_linux_amd64 /usr/bin/gdu

See the [installation page](./INSTALL.md) for other ways how to install Gdu to your system.

Or you can use Gdu directly via Docker:

    docker run --rm --init --interactive --tty --privileged --volume /:/mnt/root ghcr.io/dundee/gdu /mnt/root

## Usage

```
/* Detailed source-code truncated for AI context efficiency. */
```

## Examples

    gdu                                   # analyze current dir
    gdu -a                                # show apparent size instead of disk usage
    gdu --no-delete                       # prevent write operations
    gdu --no-view-file                    # prevent viewing file contents
    gdu <some_dir_to_analyze>             # analyze given dir
    gdu -d                                # show all mounted disks
    gdu -l ./gdu.log <some_dir>           # write errors to log file
    gdu -i /sys,/proc /                   # ignore some paths
    gdu -I '.*[abc]+'                     # ignore paths by regular pattern
    gdu -X ignore_file /                  # ignore paths by regular patterns from file
    gdu -c /                              # use only white/gray/black colors

    gdu -n /                              # only print stats, do not start interactive mode
    gdu --interactive / | tee out.txt     # force interactive mode even when stdout is piped
    gdu -p /                              # do not show progress, useful when using its output in a script
    gdu -ps /some/dir                     # show only total usage for given dir
    gdu -t 10 /                           # show top 10 largest files
    gdu --reverse-sort -n /               # show files sorted from smallest to largest in non-interactive mode
    gdu / > file                          # write stats to file, do not start interactive mode

    gdu -o- / | gzip -c >report.json.gz   # write all info to JSON file for later analysis
    zcat report.json.gz | gdu -f-         # read analysis from file

    gdu --db=tmp.badger /                 # use persistent key-value storage for saving analysis data
    gdu --db=tmp.db /                     # use persistent SQLite storage for saving analysis data
    gdu -r /                              # read saved analysis data from persistent key-value storage

    gdu --web /                           # analyze and browse the results in a web browser
    gdu --web --web-listen localhost:8080 /   # serve the web UI on a fixed address
    gdu --web --web-open=false /          # print the URL but do not open a browser

## Modes

Gdu has three modes: interactive (default), non-interactive and export.

Non-interactive mode is started automatically when TTY is not detected (using [go-isatty](https://github.com/mattn/go-isatty)), for example if the output is being piped to a file, or it can be started explicitly by using a flag. Use `--interactive` to disable this automatic fallback and force interactive mode.

In non-interactive mode (and without `--top` and `--depth` flags), gdu uses a memory-efficient analyzer that only tracks top-level directory totals.
This means memory usage stays constant regardless of how large the scanned directory tree is.
When `--top` or `--depth` flags are used, the full directory tree is built in memory as in interactive mode.

Export mode (flag `-o`) outputs all usage data as JSON, which can be later opened using the `-f` flag. In interactive mode, press `Ctrl+C` during a scan to stop scheduling new work and keep the results found so far.

By default the export includes every attribute, and directories always carry their `asize`, `dsize`, and `items` summary stats so they can be preserved on import. Use `--output-attrs=asize,dsize` to emit only selected optional attributes; `name` is always included. Available attributes are `asize`, `dsize`, `items`, `mtime`, and `notreg`.

Gdu honors `BLOCK_SIZE` and `BLOCKSIZE` in terminal output. `BLOCK_SIZE` takes precedence; both accept GNU coreutils block-size values such as `1K`, `kB`, `human-readable`, and `si`. Explicit size-format flags override these environment variables. Exported JSON always retains raw byte values.

Hard links are counted only once.

## Web UI

Gdu can serve a browser-based interface instead of the terminal UI. Run:

```
gdu --web /some/dir
```

Gdu scans the directory, prints the URL, and (by default) opens it in your
default browser. The interface shows an animated donut chart of the current
directory's contents alongside a sortable table with size bars, breadcrumb
navigation, and a disk-usage/apparent-size toggle. Scan progress is streamed
live while the analysis runs.

By default the server binds to `localhost` on a random free port. Use
`--web-listen` (or the `web.listen` config option) to pin a fixed address.

The compiled web assets are embedded in the binary, so no extra files or network
access are required.

**Security:** the web UI is read-only and has no authentication. It exposes file
names and sizes over HTTP, so keep it bound to `localhost` (the default). Binding
to a non-loopback address makes those details reachable by other hosts on the
network and prints a warning.

## File flags

Files and directories may be prefixed by a one-character
flag with following meaning:

* `!` An error occurred while reading this directory.

* `.` An error occurred while reading a subdirectory, size may be not correct.

* `@` File is symlink or socket. Symlinks can be shown as `name -> target` (the link target is displayed next to the name, like `ls -l`).

* `H` Same file was already counted (hard link).

* `e` Directory is empty.

## Configuration file

Gdu can read (and write) YAML configuration file.

`$HOME/.config/gdu/gdu.yaml` and `$HOME/.gdu.yaml` are checked for the presence of the config file by default.

See the [full list of all configuration options](configuration.md).

### Examples

* To configure gdu to permanently run in gray-scale color mode:

```
echo "no-color: true" >> ~/.gdu.yaml
```

* To set default sorting in configuration file:

```
sorting:
    by: name // size, name, itemCount, mtime
    order: desc
```

* To configure gdu to set CWD variable when browsing directories:

```
echo "change-cwd: true" >> ~/.gdu.yaml
```

* To configure the web UI (bind address and browser behavior):

```
web:
    listen: "localhost:8080"  # empty (default) = localhost + random free port
    open-browser: true        # open the default browser on start
    browser: ""               # override launcher command; empty = OS default
```

* To save the current configuration

```
gdu --write-config
```

## Styling

There are wide options for how terminals can be colored.
Some gdu primitives (like basic text) adapt to different color schemas, but the selected/highlighted row does not.

If the default look is not sufficient, it can be changed in configuration file, e.g.:

```
style:
    selected-row:
        text-color: black
        background-color: "#ff0000"
    marked:
        text-color: white
        background-color: "#6600cc"
```

## Deletion in background and in parallel (experimental)

Gdu can delete items in the background, thus not blocking the UI for additional work.
To enable:

```
echo "delete-in-background: true" >> ~/.gdu.yaml
```

Directory items can be also deleted in parallel, which might increase the speed of deletion.
To enable:

```
echo "delete-in-parallel: true" >> ~/.gdu.yaml
```

## Saving analysis data to database

Gdu can store the analysis data to a database file instead of just memory.
This allows you to save and reload analysis results later.
Both SQLite and BadgerDB are supported.

```
gdu --db analysis.sqlite /        # saves analysis data to SQLite database
gdu --db analysis.badger /        # saves analysis data to BadgerDB
gdu -r --db analysis.sqlite /     # reads saved data, does not run analysis again
```

## Running tests

    make install-dev-dependencies
    make test

## Profiling

Gdu can collect profiling data when the `--enable-profiling` flag is set.
The data are provided via embedded http server on URL `http://localhost:6060/debug/pprof/`.

You can then use e.g. `go tool pprof -web http://localhost:6060/debug/pprof/heap`
to open the heap profile as SVG image in your web browser.

## Benchmarks

Benchmarks were performed on 90G directory (100k directories, 400k files) on 500 GB SSD using [hyperfine](https://github.com/sharkdp/hyperfine).
See `benchmark` target in [Makefile](Makefile) for more info.

### Cold cache

Filesystem cache was cleared using `sync; echo 3 | sudo tee /proc/sys/vm/drop_caches`.

| Command | Mean [s] | Min [s] | Max [s] | Relative |
|:---|---:|---:|---:|---:|
| `diskus ~` | 4.489 ± 0.020 | 4.449 | 4.516 | 1.00 |
| `gdu -npc ~` | 4.716 ± 0.342 | 4.109 | 5.337 | 1.05 ± 0.08 |
| `GOMAXPROCS=80 gdu -npc ~` | 4.901 ± 1.953 | 3.627 | 9.993 | 1.09 ± 0.44 |
| `pdu ~` | 5.969 ± 0.492 | 5.567 | 6.640 | 1.33 ± 0.11 |
| `dua ~` | 6.030 ± 0.249 | 5.878 | 6.597 | 1.34 ± 0.06 |
| `dust -d0 ~` | 6.181 ± 0.311 | 6.043 | 7.053 | 1.38 ± 0.07 |
| `gdu -npc --db=tmp.badger ~` | 27.479 ± 3.015 | 25.048 | 32.777 | 6.12 ± 0.67 |
| `du -hs ~` | 30.608 ± 0.221 | 30.136 | 30.794 | 6.82 ± 0.06 |
| `duc index ~` | 32.897 ± 3.168 | 31.524 | 41.865 | 7.33 ± 0.71 |
| `ncdu -0 -o /dev/null ~` | 33.163 ± 3.482 | 31.476 | 42.979 | 7.39 ± 0.78 |
| `gdu -npc --db=tmp.db ~` | 44.989 ± 0.270 | 44.622 | 45.414 | 10.02 ± 0.07 |

### Warm cache

| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|:---|---:|---:|---:|---:|
| `diskus ~` | 270.8 ± 8.1 | 262.4 | 291.5 | 1.00 |
| `pdu ~` | 299.1 ± 4.1 | 292.1 | 305.0 | 1.10 ± 0.04 |
| `GOMAXPROCS=100 gdu -npc ~` | 459.1 ± 14.2 | 446.7 | 490.3 | 1.69 ± 0.07 |
| `gdu -npc ~` | 466.1 ± 27.9 | 421.4 | 495.3 | 1.72 ± 0.12 |
| `dua ~` | 590.6 ± 5.9 | 580.5 | 599.7 | 2.18 ± 0.07 |
| `dust -d0 ~` | 578.7 ± 3.7 | 572.2 | 586.3 | 2.14 ± 0.07 |
| `du -hs ~` | 1255.2 ± 7.4 | 1245.1 | 1273.4 | 4.63 ± 0.14 |
| `duc index ~` | 1450.5 ± 6.2 | 1440.6 | 1460.4 | 5.36 ± 0.16 |
| `ncdu -0 -o /dev/null ~` | 2222.4 ± 5.6 | 2215.6 | 2231.0 | 8.21 ± 0.25 |
| `gdu -npc --db=tmp.db ~` | 8246.7 ± 30.9 | 8181.9 | 8288.7 | 30.45 ± 0.92 |
| `gdu -npc --db=tmp.badger ~` | 15608.0 ± 3215.8 | 13960.3 | 22448.0 | 57.63 ± 12.00 |

## Alternatives

* [ncdu](https://dev.yorhel.nl/ncdu) - NCurses based tool written in pure `C` (LTS) or `zig` (Stable)
* [godu](https://github.com/viktomas/godu) - Analyzer with a carousel like user interface
* [dua](https://github.com/Byron/dua-cli) - Tool written in `Rust` with interface similar to gdu (and ncdu)
* [diskus](https://github.com/sharkdp/diskus) - Very simple but very fast tool written in `Rust`
* [duc](https://duc.zevv.nl/) - Collection of tools with many possibilities for inspecting and visualising disk usage
* [dust](https://github.com/bootandy/dust) - Tool written in `Rust` showing tree like structures of disk usage
* [pdu](https://github.com/KSXGitHub/parallel-disk-usage) - Tool written in `Rust` showing tree like structures of disk usage

## Notes

[HDD icon created by Nikita Golubev - Flaticon](https://www.flaticon.com/free-icons/hdd)

---

## File: docs/run-books.md

# Release process

1. update usage in README.md and gdu.1.md
1. `make show-man`
1. `make man`
1. commit the changes
1. tag new version with `-sa`
1. `make`
1. `git push --tags`
1. `git push`
1. release is created on GitHub from the tag, or `make release`
1. update `gdu.spec`
1. Release snapcraft, AUR, ...

## 2. Official Technical Reference & Guides (dundee/docs)

# Prometheus Documentation

This repository contains both the content and the static-site generator code for the
Prometheus documentation site.

## Contributing Changes

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for general instructions for new Prometheus contributors.

The main documentation contents of this website are located in the [`content/docs`](content/docs) directory.

Documentation concerning the Prometheus server is [maintained in the Prometheus server repository](https://github.com/prometheus/prometheus/tree/master/docs) and cloned into the website at build time.

As a guideline, please keep the documentation generally applicable and avoid use-case-specific changes.

## Prerequisites

You need to have a working Ruby environment set up (including [bundler](https://bundler.io/))
and then install the necessary gems:

```bash
cd docs
make bundle
```

## Building

To generate the static site, run:

```bash
make build
```

The resulting static site will be stored in the `output` directory.

Optionally, you can use an API token to avoid rate limits on the API. You can get an API token from https://github.com/settings/tokens/new.
```bash
export GITHUB_AUTHENTICATION='-u user:token'
```

## Development Server

To run a local server that displays the generated site, run:

```bash
# Rebuild the site whenever relevant files change:
make guard
# Start the local development server in a separate shell:
make serve
```

You should now be able to view the generated site at
[http://localhost:3000/](http://localhost:3000).

## Automatic Deployment

This site is automatically deployed using [Netlify](https://www.netlify.com/).

If you have the prerequisite access rights, you can view the Netlify settings here:

* GitHub webhook notifying Netlify of branch changes: https://github.com/prometheus/docs/settings/hooks
* Netlify project: https://app.netlify.com/sites/prometheus-docs

Changes to the `master` branch are deployed to the main site at https://prometheus.io.

Netlify also creates preview deploys for every pull request. To view these for a PR where all checks have passed:

1. In the CI section of the PR, click on "Show all checks".
2. On the "deploy/netlify" entry, click on "Details" to view the preview site for the PR.

You may have to wait a while for the "deploy/netlify" check to appear after creating or updating the PR, even if the other checks have already passed.

## License

Apache License 2.0, see [LICENSE](LICENSE).