hddviz CLI

Demo screenshot from my laptop

Motivation

Unlike Linux CLI, macOS does not have a convenient command line tool to visualize hard disk usage. This tool aims to visualize hard disk usage from your command line everywhere. It also provides a REPL interface where you can enter commands to navigate directories and visualize folder-based disk usage.

hddviz helps you to identify large files and subdirectories that are taking up a lot of space on your hard drive from your terminal. Please refer to hddviz --help for more details on how to use it.

How to install (macOS only so far.)

1. Download the tar.gz file from the releases page.
2. Extract it:

tar -xzf hddviz_*_darwin_*.tar.gz

3. There are multiple ways to add the hddviz binary as your CLI tool.

a. If you have a homebrew, then try running

# Apple Silicon
install -m 0700 hddviz /opt/homebrew/bin/hddviz

# Intel
install -m 0700 hddviz /usr/local/bin/hddviz

b. If you don't have homebrew, you can move the hddviz binary to a directory in your CLI tool path. You need to add it to PATH first:

mkdir -p "$HOME/.local/bin"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.zshrc"
source "$HOME/.zshrc"
install -m 0700 hddviz "$HOME/.local/bin/hddviz"

c. Install from source code:

Go to src/ folder and compile the code using make build. Run

go install .

This installs hddviz into:

• $GOBIN (if set), or
• $(go env GOPATH)/bin (default: $HOME/go/bin)

If hddviz is not found, add Go bin to your PATH:

echo 'export PATH="$(go env GOPATH)/bin:$PATH"' >> "$HOME/.zshrc"
source "$HOME/.zshrc"

4. Verify:

hddviz --help

5. Run:

hddviz -est

I recommend using the -est flag since this enables the concurrent scanning feature, which is much faster than the serial scanning mode. I created the -est flag since there could be some concurrency issues that I have not encountered yet. hddviz alone will guarantee the accuracy of the disk usage using the serial scanning mode.

Troubleshooting

Some of you may face the issue saying that hddviz is a malware from apple. You need to go the system settings -> privacy & security -> security. You may have the hddviz app blocked from running. Click open anyway and you should be able to run hddviz from your terminal.

Trust me, hddviz is not a malware. You can also clone the source code and build it yourself if you don't trust the binary.

Supported commands in REPL:

You can see the following commands by running help in the REPL interface. But here is a more detailed description of the supported commands in the REPL interface:

• help: Display the list of available commands and their descriptions.
• ls: List the top-K largest subdirectories under your current path.
• inspect <path>: Show summary for a path without changing the current directory. can be a relative path (including '../') or an absolute path.
• cd <path>: Change the current directory to the specified folder.
• pwd: Print the current directory path.
• quit: Exit the REPL interface.

Technical parts:

• Uses a heap for top-K largest subdirs listing
• Uses recursion to scan all directories.
• Supports concurrent scanning (sometimes overcounts file usage, so it is only used for estimation.)
• REPL interface.
• Added both blackbox and whitebox tests for scanning logic.

Selfish reasons for me to build this:

• Nice to learn golang for me.
• Motivate me to buy a Linux machine so I don't have to maintain this project and just run ncdu.

TODOs for me and any devs

Public deployment

• Write a doc for easier cli command installation and usage. The one that uses go install .
• Review .goreleaser.yml for brew public release.

Development:

Code quality:

• Better error handling and logging
  • log vs fprinln vs fmt.errorf vs errors.
• Add some unit tests for serial scanning.

Features:

Scanning features:

• Create goroutines for concurrent scanning of directories to improve performance.
  • Store the prototyped version in .idea folder
  • Write unit tests for them.
  • Add a command line flag to enable/disable concurrent scanning.

REPL features:

• A fancier welcome screen.
• Tab completion for path.
• I also need to make sure that both cd and ls support the folderName with space in it. Use both forward and backward slashes like 'cd Application\ Support'.

Potential extensions

• Support for Windows?
• File-system based scanning system to improve performance. For example, WizTree uses the Master File Table (MFT) to quickly scan NTFS file systems, which can be significantly faster than traditional scanning methods.