<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>CONTEXT.md - fork/gdu @ master</title>
<meta name="description" content="CONTEXT.md in fork/gdu at master.">
<meta property="og:title" content="CONTEXT.md - fork/gdu @ master">
<meta property="og:description" content="CONTEXT.md in fork/gdu at master.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="master" data-tip="c636c61a7fb7f1f9a9ac9306790b41a011cbabb9">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/gdu</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/gdu</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">Daniel Milde</span><span class="commit-message" data-commit="34f39961030d97ade7bb07e12c02e35bc6fcf314">feat: allow scanning multiple directories (#653)</span><span class="snapshot-sha sha" data-commit="34f39961030d97ade7bb07e12c02e35bc6fcf314">34f3996</span><time datetime="2026-09-02T21:19:46+02:00" title="2026-09-02 21:19:46 +0200">2026-09-02</time></p>
<header class="topbar"><details class="switcher"><summary>master</summary><div class="menu"><strong>branches</strong><a href="/fork/gdu/ref/ignore/">ignore</a><a class="current" href="/fork/gdu/ref/master/">master</a><a href="/fork/gdu/ref/subvolume/">subvolume</a><a class="all" href="/fork/gdu/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/gdu/">gdu</a> / <span class="cur">CONTEXT.md</span></nav>
<span class="view-stats"><span>2.6 KiB</span><span>75 lines</span></span><span class="actions"><a class="raw" href="/fork/gdu/raw/c7fec1b370b7daef6c050167e390d254bdde5ff4/CONTEXT.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h1>Context</h1>
<p>Glossary for gdu. Terms only — no implementation detail, no decisions.
Architectural decisions live in <a href="/fork/gdu/ref/master/tree/docs/adr/"><code>docs/adr/</code></a>.</p>
<h2>Item</h2>
<p>Anything gdu can put on a row: a file or a directory. Devices are not items —
they are listed by a separate screen with their own vocabulary.</p>
<h2>Scanned root</h2>
<p>A directory named on the command line, i.e. one of the starting points of a
scan. There can be more than one. Scanned roots are labelled by their absolute
path, unlike every other item, which is labelled by its base name.</p>
<h2>Virtual top level directory</h2>
<p>The synthetic directory that holds the scanned roots when there is more than
one, so that they can be listed, sorted and compared as siblings. It is not an
item on any filesystem and has no path; every other directory gdu shows does.</p>
<h2>Apparent size</h2>
<p>The size an item claims to be, i.e. the length of its contents.</p>
<h2>Disk usage</h2>
<p>The space an item actually occupies on disk, i.e. its allocated blocks. Differs
from apparent size for sparse files, for files smaller than a block, and for
hard-linked files.</p>
<p>Apparent size and disk usage are interchangeable <em>metrics</em>: exactly one of them
is displayed at a time, and the user switches between them.</p>
<h2>Displayed item count</h2>
<p>The number of items a row reports.</p>
<ul>
<li>For a <strong>directory</strong>: the number of items (files and subdirectories,
recursively) contained in its tree, <strong>not counting the directory itself</strong>.</li>
<li>For a <strong>file</strong>: 1 — a file counts itself.</li>
</ul>
<p>The asymmetry is deliberate. A file row reports the one file it stands for; a
directory row reports what is inside it. A consequence is that an empty
directory reports 0 while a file reports 1.</p>
<p>This is the authoritative count: it is what every frontend renders, and what
ordering by item count sorts on, so the number on screen and the ordering
always agree. It is distinct from the raw internal count, which includes the
directory itself.</p>
<h2>Size bar</h2>
<p>The horizontal bar drawn on each row to show that item's magnitude relative to
its siblings, measured in the currently displayed size metric (apparent size or
disk usage).</p>
<h2>Count bar</h2>
<p>The horizontal bar drawn on each row to show that item's displayed item count
relative to its siblings. Optional, and only meaningful alongside the item
count column.</p>
<h2>Bar denominator</h2>
<p>What a bar is measured against. Two modes, applying to every bar alike:</p>
<ul>
<li><strong>Sum of siblings</strong> (default) — each row's bar shows its share of the total,
so a full row of bars accounts for 100%.</li>
<li><strong>Largest sibling</strong> — the biggest sibling fills the bar and everything else
is drawn in proportion to it.</li>
</ul>
<p>Rows the user has ignored are excluded from the denominator and draw an empty
bar.</p>
</section><div class="code-panel"><pre class="code src language-markdown"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"><a-p>#</a-p> <a-tt>Context</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">Glossary for gdu. Terms only — no implementation detail, no decisions.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text">Architectural decisions live in [`docs/adr/`](docs/adr/).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text"><a-p>##</a-p> <a-tt>Item</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text">Anything gdu can put on a row: a file or a directory. Devices are not items —</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">they are listed by a separate screen with their own vocabulary.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text"><a-p>##</a-p> <a-tt>Scanned root</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text">A directory named on the command line, i.e. one of the starting points of a</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text">scan. There can be more than one. Scanned roots are labelled by their absolute</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text">path, unlike every other item, which is labelled by its base name.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text"><a-p>##</a-p> <a-tt>Virtual top level directory</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text">The synthetic directory that holds the scanned roots when there is more than</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text">one, so that they can be listed, sorted and compared as siblings. It is not an</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text">item on any filesystem and has no path; every other directory gdu shows does.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text"><a-p>##</a-p> <a-tt>Apparent size</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text">The size an item claims to be, i.e. the length of its contents.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text"><a-p>##</a-p> <a-tt>Disk usage</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text">The space an item actually occupies on disk, i.e. its allocated blocks. Differs</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text">from apparent size for sparse files, for files smaller than a block, and for</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text">hard-linked files.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text">Apparent size and disk usage are interchangeable *metrics*: exactly one of them</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text">is displayed at a time, and the user switches between them.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text"><a-p>##</a-p> <a-tt>Displayed item count</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text">The number of items a row reports.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text"><a-p>- </a-p>For a **directory**: the number of items (files and subdirectories,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text"><a-p>  </a-p>recursively) contained in its tree, **not counting the directory itself**.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text"><a-p>- </a-p>For a **file**: 1 — a file counts itself.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text"><a-p>The asymmetry is deliberate. A file row reports the one file it stands for; a</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"><a-p>directory row reports what is inside it. A consequence is that an empty</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text"><a-p>directory reports 0 while a file reports 1.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text"><a-p>This is the authoritative count: it is what every frontend renders, and what</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text"><a-p>ordering by item count sorts on, so the number on screen and the ordering</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text"><a-p>always agree. It is distinct from the raw internal count, which includes the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text"><a-p>directory itself.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text"><a-p>## </a-p><a-tt>Size bar</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text"><a-p>The horizontal bar drawn on each row to show that item&#39;s magnitude relative to</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text"><a-p>its siblings, measured in the currently displayed size metric (apparent size or</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"><a-p>disk usage).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"><a-p>## </a-p><a-tt>Count bar</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text"><a-p>The horizontal bar drawn on each row to show that item&#39;s displayed item count</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text"><a-p>relative to its siblings. Optional, and only meaningful alongside the item</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text"><a-p>count column.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text"><a-p>## </a-p><a-tt>Bar denominator</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text"><a-p>What a bar is measured against. Two modes, applying to every bar alike:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text"><a-p>- **Sum of siblings** (default) — each row&#39;s bar shows its share of the total,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text"><a-p>  so a full row of bars accounts for 100%.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text"><a-p>- **Largest sibling** — the biggest sibling fills the bar and everything else</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text"><a-p>  is drawn in proportion to it.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text">Rows the user has ignored are excluded from the denominator and draw an empty</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text">bar.</span></span></pre></div></div>
</main>
</body>
</html>
