<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>docs/adr/0001-displayed-item-count-is-authoritative.md - fork/gdu @ master</title>
<meta name="description" content="docs/adr/0001-displayed-item-count-is-authoritative.md in fork/gdu at master.">
<meta property="og:title" content="docs/adr/0001-displayed-item-count-is-authoritative.md - fork/gdu @ master">
<meta property="og:description" content="docs/adr/0001-displayed-item-count-is-authoritative.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="daaae96ee448f76d798929fae750c4d538b8637e">feat: show bar for item count  (#649)</span><span class="snapshot-sha sha" data-commit="daaae96ee448f76d798929fae750c4d538b8637e">daaae96</span><time datetime="2026-09-01T16:19:06+02:00" title="2026-09-01 16:19:06 +0200">2026-09-01</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> / <a href="/fork/gdu/ref/master/tree/docs/">docs</a> / <a href="/fork/gdu/ref/master/tree/docs/adr/">adr</a> / <span class="cur">0001-displayed-item-count-is-authoritative.md</span></nav>
<span class="view-stats"><span>2.4 KiB</span><span>57 lines</span></span><span class="actions"><a class="raw" href="/fork/gdu/raw/6a0582fcf327f452d06d32e498f25f5509ce5330/docs/adr/0001-displayed-item-count-is-authoritative.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>1. The displayed item count is authoritative</h1>
<p>Date: 2026-09-01</p>
<h2>Status</h2>
<p>Accepted</p>
<h2>Context</h2>
<p><code>Item.GetItemCount()</code> counts a directory <em>including itself</em>: an empty directory
returns 1, and a directory holding three files returns 4.</p>
<p>Three call sites derived a user-facing number from it, and they disagreed:</p>
<ul>
<li><code>tui/format.go</code> subtracted 1 for directories before rendering the item count
column.</li>
<li><code>pkg/fs.ByItemCount</code> (the comparator behind sorting by item count, used by
both the TUI and the web UI) compared the raw value.</li>
<li><code>webui/tree.go</code> serialized the raw value to the browser.</li>
</ul>
<p>So the terminal sorted by one number and printed another, and the two frontends
printed different numbers for the same directory. The mismatch was invisible in
practice until we set out to draw a <em>bar</em> proportional to the count
(issue #599): a bar that contradicts the number printed beside it is obviously
wrong in a way that a subtly misordered list is not.</p>
<p>The raw and displayed values only diverge at the boundary between an empty
directory (raw 1, displayed 0) and a file (raw 1, displayed 1), so the two
orderings differ by at most a small reshuffle — which is precisely why the
inconsistency survived this long.</p>
<h2>Decision</h2>
<p>There is one definition of the count, <code>fs.DisplayedItemCount</code>, and everything
conforms to it: the comparator, the TUI renderer, and the web UI serializer.</p>
<p>Where display and ordering disagreed, <strong>display wins</strong>. The number the user can
see is the number we sort by.</p>
<p>The file/directory asymmetry is kept: a file reports 1, a directory reports its
contents excluding itself.</p>
<h2>Consequences</h2>
<ul>
<li>Sorting by item count now places an empty directory below a file. This is a
behaviour change to existing output in both the TUI and the web UI.</li>
<li>The web UI's displayed item count for directories drops by one. This was
outside the scope of the originating issue, but leaving it would have made
the web UI exhibit the very defect being fixed in the TUI, since the
comparator is shared. The change is Go-side only — the compiled frontend in
<code>webui/dist</code> is untouched, so no Node build is required.</li>
<li>Adding a count bar becomes safe: it is drawn from the same value it is
labelled with.</li>
<li>The asymmetry is now documented rather than accidental. A uniform
"items contained" rule (file = 0) was rejected: it would render every file
row as <code>0</code> with an empty bar, which is strictly less informative.</li>
</ul>
</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>1. The displayed item count is authoritative</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">Date: 2026-09-01</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text"><a-p>##</a-p> <a-tt>Status</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text">Accepted</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</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="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">`Item.GetItemCount()` counts a directory *including itself*: an empty directory</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text">returns 1, and a directory holding three files returns 4.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text">Three call sites derived a user-facing number from it, and they disagreed:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"><a-p>- </a-p>`tui/format.go` subtracted 1 for directories before rendering the item count</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>column.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"><a-p>- </a-p>`pkg/fs.ByItemCount` (the comparator behind sorting by item count, used by</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text"><a-p>  </a-p>both the TUI and the web UI) compared the raw value.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text"><a-p>- </a-p>`webui/tree.go` serialized the raw value to the browser.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"><a-p>So the terminal sorted by one number and printed another, and the two frontends</a-p></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>printed different numbers for the same directory. The mismatch was invisible in</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text"><a-p>practice until we set out to draw a *bar* proportional to the count</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text"><a-p>(issue #599): a bar that contradicts the number printed beside it is obviously</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"><a-p>wrong in a way that a subtly misordered list is not.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text"><a-p>The raw and displayed values only diverge at the boundary between an empty</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text"><a-p>directory (raw 1, displayed 0) and a file (raw 1, displayed 1), so the two</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text"><a-p>orderings differ by at most a small reshuffle — which is precisely why the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text"><a-p>inconsistency survived this long.</a-p></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"><a-p>## </a-p><a-tt>Decision</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"><a-p>There is one definition of the count, `fs.DisplayedItemCount`, and everything</a-p></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>conforms to it: the comparator, the TUI renderer, and the web UI serializer.</a-p></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"><a-p>Where display and ordering disagreed, **display wins**. The number the user can</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"><a-p>see is the number we sort by.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text"></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>The file/directory asymmetry is kept: a file reports 1, a directory reports its</a-p></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>contents excluding itself.</a-p></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>## </a-p><a-tt>Consequences</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"></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>- Sorting by item count now places an empty directory below a file. This is a</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"><a-p>  behaviour change to existing output in both the TUI and the web UI.</a-p></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>- The web UI&#39;s displayed item count for directories drops by one. This was</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>  outside the scope of the originating issue, but leaving it would have made</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>  the web UI exhibit the very defect being fixed in the TUI, since 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>  comparator is shared. The change is Go-side only — the compiled frontend in</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"><a-p>  `webui/dist` is untouched, so no Node build is required.</a-p></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>- Adding a count bar becomes safe: it is drawn from the same value it is</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text"><a-p>  labelled with.</a-p></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 asymmetry is now documented rather than accidental. A uniform</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>  &quot;items contained&quot; rule (file = 0) was rejected: it would render every file</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>  </a-p>row as `0` with an empty bar, which is strictly less informative.</span></span></pre></div></div>
</main>
</body>
</html>
