DUC(1)

📦
version 1.4.6 · 2 versions
, in debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 DUC(1) — the duc manual, bestie edition 💖

General Commands Manual ✨ DUC(1)

okay so. welcome to the duc manual page, and honestly? you're gonna eat this up. this is the general commands manual for duc — index, query and graph disk usage. let's get into it 🫶

✨ NAME ✨

duc — index, query and graph disk usage 🎀

🌸 SYNOPSIS 🌸

duc subcommand options

like. that's it. that's the whole shape of it. subcommand first, options after. periodt 💅

🦋 DESCRIPTION 🦋

duc is a collection of tools for inspecting and visualizing disk usage. no cap, that's literally what it does.

the way it works is: duc maintains an indexed database of accumulated sizes of directories of your file system, and then lets you query that database with some tools, or create fancy sunburst graphs to show you where your bytes are. where did your bytes go?? duc knows. 👑

and bestie, it scales. duc has been tested on systems with more than 500 million files and several petabytes of storage. it is not fragile. it is not struggling. it is thriving. 🔥

🌈 USAGE 🌈

duc comes with a command line tool called duc, which is used to create, maintain and query the disk usage database. run duc help to get a list of available commands. duc help <subcommand> describes the usage of a specific subcommand. run duc help --all for an extensive list of all commands and their options. yes, --all is the "give me everything" button. iconic.

some commands might not be available on your system, depending on the exact configuration chosen when building Duc. (for example, the duc gui command is not available in the duc-nox package on Debian and Ubuntu.) so if a command is missing, it's not you, it's the build. 💀

duc allows any option to be placed either on the command line or in a configuration file. options on the command line are preceded by a double-leading-dash (--option), and some options have a corresponding short option which can be used as well with a single leading dash (-o). so like, --option or -o. both slay, both valid.

at startup duc tries to read its configuration from three locations in this particular order:

  1. /etc/ducrc
  2. ~/.config/duc/ducrc
  3. ~/.ducrc
  4. ./.ducrc

(yes that's four entries, don't come for me, the original says "three locations" and then lists four paths — I am simply reporting the lore fr fr 🙈)

a configuration file consists of sections and parameters. the section names correspond to the duc subcommands for which the parameters in that section apply. a section begins with the name of the section in square brackets and continues until the next section begins. sections contain parameters, one per line, which consist of a single option name for boolean flags, or an option name and a value for options which take a value. see the EXAMPLES section for an example of the configuration file format. iykyk.

🎀 CREATING THE INDEX 🎀

duc needs an index file of the file system before it is able to show any information. so like, no index, no vibes. to create the index, run the duc index command. for example, to create an index of your home directory run duc index ~

$ duc index /usr
Skipping lost+found: Permission denied
Indexed 333823 files and 48200 directories, (35.0GB total) in 1 seconds

look at that output. 333823 files. 48200 directories. 35.0GB total. in 1 seconds. we love a productive queen ✨

the default location of the database is $HOME/.duc.db. to use a different database location, use the DUC_DATABASE environment variable or specify the database location with the --database argument. your db, your rules.

you can run duc index at any time later to rebuild the index. refresh, rebuild, re-slay. 🦋

by default duc indexes all directories it encounters during file system traversal, including special file systems like /proc and /sys, and network file systems like NFS or Samba mounts. yes, all of them. the whole buffet. there are a few options to select what parts of your filesystem you want to include or exclude from the scan, so check the documentation below for the options --one-file-system, --exclude, --fs-exclude and --fs-include for more details. 💅

👑 QUERYING THE INDEX 👑

duc has various subcommands for querying or exploring the index. (note that depending on your configuration, some of these commands might not be available — remember the duc-nox thing? yeah. that.)

  • duc info shows a list of available directory trees in the database, and the time and date of the last scan. it's giving receipts 🧾
  • duc ls lists all files and directories under the given path on the console. classic, reliable, never misses.
  • duc ui runs a ncurses based console user interface for exploring the file system usage. terminal girlies rise 🫶
  • duc gui starts a graphical (X11) interface representing the file system in a sunburst graph. click on a directory to redraw the graph from the perspective of the selected directory. click in the center of the graph to go up one directory in the tree. it's giving main character energy in graph form 🌟

✨ OPTIONS ✨

okay bestie this is the big one 💅 this section lists every subcommand and spells out what each one does plus all its options. grab a snack, we're going shopping 🛍️

🌸 Global options 🌸

these ones hit different — they work on all Duc subcommands, every single one, no exceptions 🫶

  • --debug — crank the verbosity all the way up to debug level
  • -h, --help — show help
  • -q, --quiet — quiet mode, do not print any warning
  • -v, --verbose — increase verbosity
  • --version — output version information and exit

🎀 duc help 🎀

Options for command duc help [options]:

duc help [options]
  • -a, --all — show complete help for all commands

💖 duc index 💖

the index subcommand does a recursive scan of whatever paths you hand it on the filesystem, and it calculates the inclusive size of all directories. the results get written to the index, and later you can query them with any of the other duc tools. it's giving main character energy fr fr 👑

Options for command duc index [options] PATH ...:

duc index [options] PATH ...
  • -b, --bytes — show file size in exact number of bytes
  • -d, --database=VAL — use database file VAL
  • -e, --exclude=VAL — exclude files matching VAL
  • -H, --check-hard-links — count hard links only once. if two or more hard links point to the same file, only one of the hard links is displayed and counted. no double counting in this house 🙅‍♀️
  • -f, --force — force writing in case of corrupted db
  • --fs-exclude=VAL — exclude file system type VAL during indexing. VAL is a comma separated list of file system types as found in your systems fstab, for example ext3,ext4,dosfs
  • --fs-include=VAL — include file system type VAL during indexing. VAL is a comma separated list of file system types as found in your systems fstab, for example ext3,ext4,dosfs
  • --hide-file-names — hide file names in index (privacy). the names of directories will be preserved, but the names of the individual files will be hidden 🔒
  • -U, --uid=VAL — limit index to only files/dirs owned by uid
  • -u, --username=VAL — limit index to only files/dirs owned by username
  • -m, --max-depth=VAL — limit directory names to given depth. when this option is given duc will traverse the complete file system, but will only the first VAL levels of directories in the database to reduce the size of the index
  • -x, --one-file-system — skip directories on different file systems
  • -p, --progress — show progress during indexing
  • --dry-run — do not update database, just crawl
  • --uncompressed — do not use compression for database. Duc enables compression if the underlying database supports this. This reduces index size at the cost of slightly longer indexing time

🦋 duc info 🦋

Options for command duc info [options]:

duc info [options]
  • -a, --apparent — show apparent instead of actual file size
  • -b, --bytes — show file size in exact number of bytes
  • -d, --database=VAL — select database file to use [~/.duc.db]

🍓 duc ls 🍓

the ls subcommand queries the duc database and lists the inclusive size of all files and directories on the given path. if you don't give it a path, it lists the current working directory. so chill of it honestly ✨

Options for command duc ls [options] [PATH]...:

duc ls [options] [PATH]...
  • -a, --apparent — show apparent instead of actual file size
  • --ascii — use ASCII characters instead of UTF-8 to draw tree
  • -b, --bytes — show file size in exact number of bytes
  • -F, --classify — append file type indicator (one of */) to entries
  • -c, --color — colorize output (only on ttys)
  • --count — show number of files instead of file size
  • -d, --database=VAL — select database file to use [~/.duc.db]
  • -D, --directory — list directory itself, not its contents
  • --dirs-only — list only directories, skip individual files
  • --full-path — show full path instead of tree in recursive view
  • -g, --graph — draw graph with relative size for each entry
  • -l, --levels=VAL — traverse up to ARG levels deep [4]
  • -n, --name-sort — sort output by name instead of by size
  • -R, --recursive — recursively list subdirectories

💜 duc xml 💜

Options for command duc xml [options] [PATH]:

duc xml [options] [PATH]
  • -a, --apparent — interpret min_size/-s value as apparent size
  • -d, --database=VAL — select database file to use [~/.duc.db]
  • -x, --exclude-files — exclude file from xml output, only include directories
  • -s, --min_size=VAL — specify min size for files or directories

🌈 duc json 🌈

Options for command duc json [options] [PATH]:

duc json [options] [PATH]
  • -a, --apparent — interpret min_size/-s value as apparent size
  • -d, --database=VAL — select database file to use [~/.duc.db]
  • -x, --exclude-files — exclude file from json output, only include directories
  • -s, --min_size=VAL — specify min size for files or directories

🔥 duc graph 🔥

the graph subcommand queries the duc database and generates a sunburst graph showing the disk usage of the given path. no path? then a graph gets created for the current working directory. aesthetic AND informative, we love to see it 🌞

by default the graph is written to the file duc.png, which you can override with the -o/--output option. and if you want the output sent to stdout, use the special file name -. yes really, just a dash 💫

Options for command duc graph [options] [PATH]:

duc graph [options] [PATH]
  • -a, --apparent — Show apparent instead of actual file size
  • -d, --database=VAL — select database file to use [~/.duc.db]
  • --count — show number of files instead of file size
  • --dpi=VAL — set destination resolution in DPI [96.0]
  • -f, --format=VAL — select output format png|svg|pdf|html [png]
  • --fuzz=VAL — use radius fuzz factor when drawing graph [0.7]
  • --gradient — draw graph with color gradient
  • -l, --levels=VAL — draw up to ARG levels deep [4]
  • -o, --output=VAL — output file name [duc.png]
  • --palette=VAL — select palette. available palettes are: size, rainbow, greyscale, monochrome, classic
  • --ring-gap=VAL — leave a gap of VAL pixels between rings
  • -s, --size=VAL — image size [800]

🧚 duc cgi 🧚

Options for command duc cgi [options] [PATH]:

duc cgi [options] [PATH]
  • -a, --apparent — Show apparent instead of actual file size
  • -b, --bytes — show file size in exact number of bytes
  • --count — show number of files instead of file size
  • --css-url=VAL — url of CSS style sheet to use instead of default CSS
  • -d, --database=VAL — select database file to use [~/.duc.db]
  • --dpi=VAL — set destination resolution in DPI [96.0]
  • --footer=VAL — select HTML file to include as footer
  • --fuzz=VAL — use radius fuzz factor when drawing graph [0.7]
  • --gradient — draw graph with color gradient
  • --header=VAL — select HTML file to include as header
  • -l, --levels=VAL — draw up to ARG levels deep [4]
  • --list — generate table with file list
  • --palette=VAL — select palette. available palettes are: size, rainbow, greyscale, monochrome, classic
  • --ring-gap=VAL — leave a gap of VAL pixels between rings
  • -s, --size=VAL — image size [800]
  • --tooltip — enable tooltip when hovering over the graph. enabling the tooltip will cause an asynchronous HTTP request every time the mouse is moved and can greatly increase the HTTP traffic to the web server
ok so real talk on that last one — --tooltip looks cute but it fires an async HTTP request every time the mouse moves and can greatly increase the HTTP traffic to your web server. no cap, know what you're signing up for 💀

👑 duc gui 👑

the gui subcommand queries the duc database and runs an interactive graphical utility for exploring the disk usage of the given path. if no path is given, the current working directory is explored. very demure, very mindful, very explorative 🎀

these keys are how you navigate and alter the graph:

+           increase maximum graph depth
-           decrease maximum graph depth
0           Set default graph depth
a           Toggle between apparent and actual disk usage
b           Toggle between exact byte count and abbreviated sizes
c           Toggle between file size and file count
f           toggle graph fuzz
g           toggle graph gradient
p           toggle palettes
backspace   go up one directory

Options for command duc gui [options] [PATH]:

duc gui [options] [PATH]
  • -a, --apparent — show apparent instead of actual file size
  • -b, --bytes — show file size in exact number of bytes
  • --count — show number of files instead of file size
  • --dark — use dark background color
  • -d, --database=VAL — select database file to use [~/.duc.db]
  • --fuzz=VAL — use radius fuzz factor when drawing graph
  • --gradient — draw graph with color gradient
  • -l, --levels=VAL — draw up to VAL levels deep [4]
  • --palette=VAL — select palette. available palettes are: size, rainbow, greyscale, monochrome, classic
  • --ring-gap=VAL — leave a gap of VAL pixels between rings

🩷 duc ui 🩷

the ui subcommand queries the duc database and runs an interactive ncurses utility for exploring the disk usage of the given path. no path given? the current working directory gets explored. terminal girlies, this one's for you 🫶

these keys are how you navigate and alter the file system:

up, pgup, j:     move cursor up
down, pgdn, k:   move cursor down
home, 0:         move cursor to top
end, $:          move cursor to bottom
left, backspace: go up to parent directory (..)
right, enter:    descent into selected directory
a:               toggle between actual and apparent disk usage
b:               toggle between exact and abbreviated sizes
c:               Toggle between file size and file count
h:               show help. press 'q' to return to the main screen
n:               toggle sort order between 'size' and 'name'
o:               try to open the file using xdg-open
q, escape:       quit

Options for command duc ui [options] [PATH]:

duc ui [options] [PATH]
  • -a, --apparent — show apparent instead of actual file size
  • -b, --bytes — show file size in exact number of bytes
  • --count — show number of files instead of file size
  • -d, --database=VAL — select database file to use [~/.duc.db]
  • -n, --name-sort — sort output by name instead of by size
  • --no-color — do not use colors on terminal output

✨ CGI INTERFACING ✨

ok so plot twist bestie: the duc binary also has a rudimentary CGI interface 💅 — right now it's only been tested with apache, jsyk. What it does is generate a simple HTML page with a list of indexed directories and shows you a clickable graph for navigating the file system 🦋. And if you pass the --list option, it also writes out a list of top sized files/dirs. Iconic behaviour, honestly.

Configuration is done by creating a simple shell script as .cgi in a directory which is configured for CGI execution by your web server (usually /usr/lib/cgi-bin). The shell script should simply start duc, and pass the location of the database to navigate. That's it, no drama 🎀

An example duc.cgi script would be

#!/bin/sh
/usr/local/bin/duc cgi -d /home/jenny/.duc.db
  • Make sure the database file is readable by the user (usually www-data) 😭 this one gets people every time
  • Debugging is best done by inspecting the web server's error log 🔍
  • Make sure the .cgi script has execute permissions (chmod +x duc.cgi) — no exec bit, no party 🎉

Some notes:

  • The HTML page is generated with a simple embedded CSS style sheet. If the style is not to your liking you can provide an external CSS url with the --css-url option which will then be used instead of the embedded style definition 💖
  • Add the option --list to generate a table of top sized files and directories in the HTML page 📊
  • The options --header and --footer allow you to insert your own HTML code before and after the main. 🌸
The current CGI configuration is not very flexible, nor secure. It is not advised to run the CGI from public reachable web servers, use at your own risk. 💀 fr fr, listen to the manpage on this one.

🌈 A NOTE ON FILE SIZE AND DISK USAGE 🌈

bestie this is the part where everyone gets confused, so let's lock in 🫶

The concepts of 'file size' and 'disk usage' can be a bit confusing. Files on disk have an apparent size, which indicates how much bytes are in the file from the users point of view; this is the size reported by tools like ls -l. The apparent size can be any number, from 0 bytes up to several TB. The actual number of bytes which are used on the filesystem to store the file can differ from this apparent size for a number of reasons: disks store data in blocks, which cause files to always take up a multiple of the block size, files can have holes ('sparse' files), and other technical reasons. This number is always a multiple of 512, which means that the actual size used for a file is almost always a bit more then its apparent size. 💅

Duc has two modes for counting file sizes:

  • apparent size: this is the size as reported by ls. This number indicates the file length, which is usually smaller then the actual disk usage.
  • actual size: this is the size as reported by du and df. The actual file size tells you how much disk is actually used by a file, and is always a multiple of 512 bytes.

The default mode used by duc is to use the 'actual size'. Most duc commands to report disk usage (duc ls, duc graph, duc ui, etc) have an option to change between these two modes (usually the -a), or use the a key to toggle. 🎀

🧚 BUILDING from git 🧚

If you use git clone to pull down the latest release, you will have to do the following:

git clone https://github.com/zevv/duc
cd duc
autoreconf -i

Then you can run the regular

./configure [ options ]
make

to the regular build of the software. slay ✨

A note for Redhat and derivates users. The package providing the development file for lmdb (lmdb-devel) does not include a lmdb.pc pkgconfig file. This could lead to errors during the configure phase:

checking for LMDB... no
configure: error: Package requirements (lmdb) were not met:

To avoid the need to call pkg-config, you may set the environment variables LMDB_CFLAGS and LMDB_LIBS:

LMDB_CFLAGS=" " LMDB_LIBS=-llmdb ./configure --with-db-backend=lmdb [ options ]

iykyk 😭

💖 EXAMPLES 💖

Index the /usr directory, writing to the default database location ~/.duc.db:

$ duc index /usr

List all files and directories under /usr/local, showing relative file sizes in a graph:

$ duc ls -Fg /usr/local
  4.7G lib/                 [+++++++++++++++++++++++++++++++++++++++++++]
  3.1G share/               [++++++++++++++++++++++++++++               ]
  2.7G src/                 [++++++++++++++++++++++++                   ]
814.9M bin/                 [+++++++                                    ]
196.6M include/             [+                                          ]
 66.6M x86_64-w64-mingw32/  [                                           ]
 59.9M local/               [                                           ]
 38.8M i686-w64-mingw32/    [                                           ]
 20.3M sbin/                [                                           ]
 13.6M lib32/               [                                           ]
 13.3M libx32/              [                                           ]

or use the -R options for the tree view:

$ duc ls -RF /etc/logcheck
 24.0K `+- ignore.d.server/
  4.0K  |  `+- hddtemp
  4.0K  |   |- ntpdate
  4.0K  |   |- lirc
  4.0K  |   |- rsyslog
  4.0K  |   `- libsasl2-modules
  8.0K  |- ignore.d.workstation/
  4.0K  |   `- lirc
  8.0K  `- ignore.d.paranoid/
  4.0K      `- lirc

Start the graphical interface to explore the file system using sunburst graphs:

$ duc gui /usr

Generate a graph of /usr/local in .png format:

$ duc graph -o /tmp/usr.png /usr

The following sample configuration file defines default parameters for the duc ls and duc ui commands and defines a global option to configure the database path which is used by all subcommands

[global]
database /var/cache/duc.db

[ls]
recursive
classify
color

[ui]
no-color
apparent

👑 FREQUENTLY ASKED QUESTIONS 👑

  • What does the error 'Database version mismatch mean?'

The layout of the index database sometimes changes when new features are implemented. When you get this error you have probably upgraded to a newer version. Just remove the old database file and rebuild the index. 💅 easy fix, no stress.

  • Duc crashes with a segmentation fault, is it that buggy?

By default Duc uses the Tokyocabinet database backend. Tokyocabinet is pretty fast, stores the database in a single file and has nice compression support to keep the database small. Unfortunately, it is not always robust and sometimes chokes on corrupt database files. Try to remove the database and rebuild the index. If the error persists contact the authors. 😭

  • Some of the Duc subcommands like duc gui are not available on my system?

Depending on the configuration that was chosen when building Duc, some options might or might not be available in the duc utility. For example, on Debian or Ubuntu Duc comes in two flavours: there is a full featured package called duc, or a package without dependencies on X-windows called duc-nox, for which the latter lacks the duc gui command. 🦋

  • duc index is hogging my system and using a lot of CPU and I/O!

Traversing a file system is hard work - which is the exact reason why Duc exists in the first place. You can use the default tools to make Duc behave nice towards other processes on your machine, use something like:

nice 19 ionice -c 3 duc index [options]

This makes duc index run with the lowest CPU and I/O scheduler priorities, which is nicer to all the other processes on your machine. 🌸

🎀 FILES 🎀

At startup duc tries to read its configuration from three locations in this particular order: /etc/ducrc, ~/.config/duc/ducrc, ~/.ducrc and ./.ducrc. 📂

Duc mainains an index of scanned directories, which defaults to ~/.duc.db. All tools take the -d/--database option to override the database path. 💾

💜 AUTHORS 💜

  • Ico Doornekamp duc@zevv.nl
  • John Stoffel john@stoffel.org

Other contributors can be found in the Git log at GitHub. 🫶

⭐ LICENSE ⭐

Duc is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 dated June, 1991. Duc is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. 💀

and that's the whole page bestie!! 🎉 this one's from July 2022, DUC(1) — go forth and index your filesystem, you absolute icon 👑💖✨

📦 where this page comes from