1# QDirStat 2<img src="https://github.com/shundhammer/qdirstat/blob/master/src/icons/qdirstat.svg" height="64"> 3 4Qt-based directory statistics: KDirStat without any KDE -- from the author of 5the original KDirStat. 6 7(c) 2015-2021 Stefan Hundhammer <Stefan.Hundhammer@gmx.de> 8 9Target Platforms: Linux, BSD, Unix-like systems 10 11License: GPL V2 12 13Updated: 2021-08-28 14 15 16## Screenshot 17 18[<img width="900" src="https://github.com/shundhammer/qdirstat/blob/master/screenshots/QDirStat-main-win.png">](https://raw.githubusercontent.com/shundhammer/qdirstat/master/screenshots/QDirStat-main-win.png) 19 20_Main window screenshot - notice the multi-selection in the tree and the treemap_ 21 22 23## Overview 24 25QDirStat is a graphical application to show where your disk space has gone and 26to help you to clean it up. 27 28This is a Qt-only port of the old Qt3/KDE3-based KDirStat, now based on the 29latest Qt 5. It does not need any KDE libs or infrastructure. It runs on every 30X11-based desktop on Linux, BSD and other Unix-like systems and of course in a 31Docker container. 32 33QDirStat has a number of new features compared to KDirStat. To name a few: 34 35- Multi-selection in both the tree and the treemap. 36 37- Unlimited number of user-defined cleanup actions. 38 39- Properly show errors of cleanup actions (and their output, if desired). 40 41- Configurable file categories (MIME types), treemap colors, exclude rules, 42 tree columns. 43 44- Package manager support: 45 - Show what software package a system file belongs to. 46 - [Packages view](doc/Pkg-View.md) showing disk usage of installed software 47 packages and their individual files. 48 - [Unpackaged files view](doc/Unpkg-View.md) showing what files in system 49 directories do not belong to any installed software package. 50 51- New views: 52 - Disk usage per file type (by filename extension). 53 - File size histogram view. 54 - [File Age View](doc/File-Age-Statistics.md) 55 - Free, used and reserved disk size for each mounted filesystem (like _df_) 56 57See section [_New Features_](#new-features) for more details. 58 59 60## Table of Contents 61 621. [Screenshot](#screenshot) 631. [Latest Stable Release](#latest-stable-release) 641. [Latest News](#latest-news) 651. [History](#history) 661. [Related Software](#related-software): KDirStat, WinDirStat, K4DirStat and more 671. [Motivation / Rant: Why?](#motivation--rant-why) 681. [Features](#features) 691. [MacOS X Compatibility](#macos-x-compatibility) 701. [Windows Compatibility](#windows-compatibility) 711. [Ready-made Packages](#ready-made-packages) 721. [QDirStat Docker Container](#qdirstat-docker-container) 731. [Building](#building) 741. [Contributing](#contributing) 751. [Troubleshooting](#troubleshooting) 761. [Further Reading](#further-reading) 771. [Packaging Status](#packaging-status) 781. [Donate](#donate) 79 80 81## More Screenshots 82 83 84[<img align="top" height="237" src="https://github.com/shundhammer/qdirstat/blob/master/screenshots/QDirStat-file-type-stats.png">](https://raw.githubusercontent.com/shundhammer/qdirstat/master/screenshots/QDirStat-file-type-stats.png) 85[<img align="top" height="169" src="https://github.com/shundhammer/qdirstat/blob/master/screenshots/QDirStat-cleanup-output.png" >](https://raw.githubusercontent.com/shundhammer/qdirstat/master/screenshots/QDirStat-cleanup-output.png) 86[<img align="top" height="150" src="https://github.com/shundhammer/qdirstat/blob/master/screenshots/QDirStat-column-config.png" >](https://raw.githubusercontent.com/shundhammer/qdirstat/master/screenshots/QDirStat-column-config.png) 87 88[<img width="700" src="https://github.com/shundhammer/qdirstat/blob/master/screenshots/QDirStat-locating-file-types.png">](https://raw.githubusercontent.com/shundhammer/qdirstat/master/screenshots/QDirStat-locating-file-types.png) 89 90 91[<img align="top" width="180" src="https://github.com/shundhammer/qdirstat/blob/master/screenshots/QDirStat-config-cleanups.png">](https://raw.githubusercontent.com/shundhammer/qdirstat/master/screenshots/QDirStat-config-cleanups.png) 92[<img align="top" width="180" src="https://github.com/shundhammer/qdirstat/blob/master/screenshots/QDirStat-config-mime.png" >](https://raw.githubusercontent.com/shundhammer/qdirstat/master/screenshots/QDirStat-config-mime.png) 93[<img align="top" width="180" src="https://github.com/shundhammer/qdirstat/blob/master/screenshots/QDirStat-config-exclude.png" >](https://raw.githubusercontent.com/shundhammer/qdirstat/master/screenshots/QDirStat-config-exclude.png) 94[<img align="top" width="180" src="https://github.com/shundhammer/qdirstat/blob/master/screenshots/QDirStat-config-general.png" >](https://raw.githubusercontent.com/shundhammer/qdirstat/master/screenshots/QDirStat-config-general.png) 95 96 97[<img align="top" height="220" src="https://raw.githubusercontent.com/shundhammer/qdirstat/master/screenshots/QDirStat-histogram.png">](https://raw.githubusercontent.com/shundhammer/qdirstat/master/screenshots/QDirStat-histogram.png) 98[<img align="top" height="220" src="https://github.com/shundhammer/qdirstat/blob/master/screenshots/QDirStat-file-age-months.png" >](https://raw.githubusercontent.com/shundhammer/qdirstat/master/screenshots/QDirStat-file-age-months.png) 99 100 101_Full-size images and descriptions on the [Screenshots Page](https://github.com/shundhammer/qdirstat/blob/master/screenshots/Screenshots.md)_ 102 103 104----------------------- 105 106## Donate 107 108QDirStat is Free Open Source Software. 109 110If you find it useful, please consider donating. 111You can donate any amount of your choice via PayPal: 112 113[![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=EYJXAVLGNRR5W) 114 115 116## Latest Stable Release 117 118**QDirStat V1.8** 119 120See the [release announcement](https://github.com/shundhammer/qdirstat/releases). 121 122Download installable binary packages for various Linux distributions here: 123[Ready-made packages](#ready-made-packages) 124 125 126## Latest News 127 128 129- 2021-08-28 **New stable release: 1.8** 130 131 **Summary:** 132 133 - New view: _File Age Statistics_ 134 135 - Navigation history like in a web browser (_Back_, _Forward_) 136 137 - Bug fixes 138 139 - Some small improvements 140 141 142 **Details:** 143 144 - New view: _File Age Statistics_ 145 146 [<img src="https://github.com/shundhammer/qdirstat/blob/master/screenshots/QDirStat-file-age-years.png" width="250">](https://raw.githubusercontent.com/shundhammer/qdirstat/master/screenshots/QDirStat-file-age-years.png) 147 [<img src="https://github.com/shundhammer/qdirstat/blob/master/screenshots/QDirStat-file-age-months.png" width="250">](https://raw.githubusercontent.com/shundhammer/qdirstat/master/screenshots/QDirStat-file-age-months.png) 148 [<img src="https://github.com/shundhammer/qdirstat/blob/master/screenshots/QDirStat-file-age-long-ago.png" width="250">](https://raw.githubusercontent.com/shundhammer/qdirstat/master/screenshots/QDirStat-file-age-long-ago.png) 149 150 This shows the number of files per year and/or per month that were last 151 modified in that year or month, together with the total size of those files 152 and a percent bar for both (number and total size). 153 154 - New documentation for that view: [File Age Statistics](doc/File-Age-Statistics.md) 155 156 - Navigation history for directories like in a web browser: 157 158 - New buttons _Back_ / _Forward_ in the tool bar 159 160 - Standard keyboard shortcuts `[Alt] [Cursor Left]` / 161 `[Alt] [Cursor Right]` like in all common web browsers 162 163 - Support for _Back_ / _Forward_ mouse buttons if the mouse has them 164 165 - History menu on those buttons (long press on the buttons) for the last 16 166 directories 167 168 169 - Internal restructuring and refactoring to keep the code maintainable 170 171 - Bug fixes: 172 173 - Fixed [GitHub issue #169](https://github.com/shundhammer/qdirstat/issues/169): 174 Shorten path components in the breadcrumb widget for insanely long paths. 175 176 - Now closing a left-over _Permissions error_ panel when refreshing from disk. 177 After the re-read, the permissions error may no longer be there. 178 179 180 - Small improvements: 181 182 - In the _Mounted Filesystems_ window, don't show inactive mounts managed 183 by the automounter anymore. 184 185 - In the _Open Directory_ window, automatically open the first directory 186 level if a path was clicked in the _Places_ list on the left, and scroll 187 the tree on the right so that path is at the top. 188 189 - Added a little margin to the left in the main window's tree view for the 190 _Size_ column so it looks now less cramped. 191 192------------ 193 194- 2021-06-21 [QDirStat AppImage and why I don't like it](https://github.com/shundhammer/qdirstat/issues/168) 195 196 TL;DR: 197 - It's big and fat (113 MB) 198 - It's an outdated version (QDirStat 1.6.1 from 16 months ago) 199 - It doesn't even tell you what version it contains 200 - It still needs a fairly recent version of GLibc, so you can't run it on Ubuntu 18.04 LTS 201 - It's unclear if at least the libraries inside (e.g. the Qt libs) are up to date 202 203------------- 204 205 206 207_See [DevHistory.md](doc/DevHistory.md) 208for older entries._ 209 210 211## History 212 213 214This is just a rough summary. For more details, see [DevHistory.md](doc/DevHistory.md). 215 216 217- 2021-08-28 New stable release: 1.8 218 219 - New view: _File Age Statistics_ 220 221 - Navigation history like in a web browser (_Back_, _Forward_) 222 223 - Bug fixes 224 225 - Some small improvements 226 227 228- 2021-04-05 New stable release: 1.7.1 229 230 - Added a "Discover" toplevel menu with actions to easily find 231 - the largest files 232 - the newest files 233 - the oldest files 234 - files with multiple hard links 235 - broken symbolic links 236 - sparse files 237 238 - Now showing the target of symbolic links in the details panel. 239 If the target does not exist, a **Broken Link** warning is also shown. 240 241 - Menu reorganization. The new toplevel menus are now: 242 243 File, Edit, View, Go To, Discover, Clean up, Help 244 245 246- 2020-07-26 New stable release: 1.7 247 248 - Closing the gap between sizes reported by QDirstat and sizes reported by 249 the `du` command: Now also taking the allocated size into account. 250 251 - Now also displaying the allocated size where it makes sense. 252 253 - New "Mounted Filesystems" window showing output similar to the `df` command 254 (but without the cruft). 255 256 - New directory selection dialog showing all (real) filesystems. 257 258 259- 2020-02-13 New stable release: 1.6.1 260 261 - Much better handling for "permission denied" errors while reading directories 262 263 - Now showing the exact byte size (134 495 994 Bytes instead of 128.3 MB) 264 upon mouse click 265 266 - New optional tree column "Oldest File" (not enabled by default) 267 268 269- 2019-07-22 New stable release: V1.6 270 271 - New _packages_ view 272 273 - New _unpackaged files_ view 274 275 - Performance improvements while reading directories 276 277 - Vast Performance improvement for huge directories 278 (100.000+ entries in a single directory) 279 280 281- 2018-11-07 New stable release: V1.5 282 283 - New _details_ panel 284 285 - Package manager support to show what software package a file belongs to 286 287 - New _breadcrumbs_ navigation 288 289 - Switchable tree layouts L1 / L2 / L3 290 291 292- 2017-06-04 New stable release: V1.4 293 294 - New _file size statistics_ with histogram 295 296 - Shading for empty space in the treemap for lots of very small files 297 298 299- 2017-03-05 New stable release: V1.3 300 301 - New _file type_ view 302 303 - Locate files of a certain type (filename extension) in the tree 304 305 306- 2017-01-03 New stable release: V1.2 307 308 - Improved Btrfs subvolumes support 309 310 311- 2016-10-31 New stable release: V1.1-Pumpkin 312 313 - Bug fixes 314 315 - Split up the config file into several ones 316 317 318- 2016-05-16 First stable release: V1.0 319 320- 2016-04-08 Beta 3 release 321 322- 2016-03-20 Beta 2 release 323 324- 2016-02-06 Beta 1 release 325 326- 2015-11-28 QDirStat project start: Ported from the old KDE 3 KDirStat 327 328- Predecessor: KDE 3 **KDirStat** 329 330 - 2006-06-01 KDirStat 2.5.3: The last KDE3 based version. 331 332 - 2003: Bernhard Seifert wrote **WinDirStat** based on the KDirStat idea of 333 coupling a tree view and a treemap and providing cleanup actions. 334 335 - 2003-01-05 KDirStat 2.3.3: Treemaps 336 337 - 2002-02-25 KDirStat 2.0.0: Complete rewrite for KDE 2 / Qt 2 338 339 - 2000-01-21 KDirStat 0.86 for KDE 1 announced: First public version. 340 341 342## Related Software 343 344### KDirStat and QDirStat 345 346KDirStat was the first program of this kind (combining a traditional tree view 347with a treemap), also written by the same author as QDirStat. It was made for 348KDE 1 back in early 2000; later ported to KDE 2, then KDE 3. 349 350QDirStat is based on that code, but made independent of any KDE libraries or 351infrastructure, so it has much fewer library and package dependencies; 352basically only the Qt 5 libs and libz, both of which most Linux / BSD machines 353have installed anyway if there is any graphical desktop installed. 354 355 356### WinDirStat and QDirStat 357 358There are lots of articles and user forum comments about QDirStat being a "nice 359Linux port of WinDirStat". Well, nothing could be further from the truth: 360**WinDirStat is a Windows port of KDirStat**, the predecessor of QDirStat. 361 362So it's the other way round: **The Linux version was there first**, and 363somebody liked it so much that he wrote a Windows version based on that 364idea. That's a rare thing; usually people port Windows originals to Linux. 365 366See also https://windirstat.net/background.html and the WinDirStat "About" 367dialog. 368 369 370 371### QDirStat and K4DirStat 372 373K4DirStat is a port to KDE 4 / Qt 4 of the old KDE 3 / Qt 3 KDirStat. QDirStat is 374independent of that; it is based on the old KDE 3 KDirStat directly. 375 376 377### Other 378 379- Baobab 380- Filelight 381- ncdu 382- du 383 384See 385[Disk Usage Tools Compared](https://github.com/shundhammer/qdirstat/wiki/disk-usage-tools-compared): 386QDirStat vs. K4DirStat vs. Baobab vs. Filelight vs. ncdu (including benchmarks) 387in the Wiki. 388 389 390## Motivation / Rant: Why? 391 392After having used KDE since its early days (since about 1998), I didn't like 393the direction anymore that KDE has been taking. I loved KDE 1, KDE 2, KDE 3943. When KDE 4 came along, it took me a long time to try to adopt it, and when I 395did, I moved back to KDE 3 after a short while, then tried again with the next 396release, moved back again -- several times. 397 398I really tried to like it, but whenever I thought I tamed it to meet my 399requirements, a new version came along that introduced yet another annoyance. 400 401To name a few: 402 403- A lot of things that used to be user configurable in KDE 3 are not 404 configurable anymore, and when you approach the KDE 4/5 developers about 405 that, they will tell you that this is intentional, and they do not intend to 406 bring those config options back. Well, thanks a lot; this is the Apple 407 approach where they think they know what is good for you, and you are just 408 too stupid. 409 410- Konqueror as the old central tool is as good as dead. It's still there as an 411 alternate file manager (for those who find it), but the primary one is the 412 dumbed-down Dolphin that I consider unusable: It's only useful for complete 413 newbies, not for power users. The web browser part of Konqueror is so 414 outdated that you can't do much with it with most modern web sites, so the 415 great integration of web and local file manager that was the major strong 416 point of Konqueror (and thus KDE) no longer exists. 417 418- I don't like the fact that I can't simply put icons on my desktop anymore -- 419 no, I have to create a plasmoid first as a container, and those things keep 420 doing weird stuff that drives every user crazy. With one false move of your 421 mouse, it might be gone, change shape, move to another place or whatever. 422 423- I also don't like the desktop search that eats resources like there is no 424 tomorrow (disk space, disk I/O, CPU usage) and that for all practical 425 purposes you can't get rid of. 426 427- I don't like the fact that the mail client relies on that MySQL based 428 framework called _Akonadi_ that is not only resource-hungry, but also so 429 fragile that I had to use the _akonadiconsole_ lots of times just to bring it 430 back to life. Seriously, if I as a Linux system developer have a hard time 431 doing that, what is a normal user expected to do? 432 433- Activities vs. multiple desktops. I tried to use both, but they don't 434 integrate well. The desktops previewer is far inferior to the old one from 435 KDE3: Only monochrome rectangles, no real preview. The activities plasmoid 436 keeps rearranging my carefully placed and named activities at random. WTF?! 437 438- Everything is so fragmented that not even the naming is clear anymore. What 439 used to be KDE is now a jumble of the KF Framework, the KF libs, the KF apps 440 and the Plasma desktop. Yeah, great job, folks; people used to know what KDE 441 stood for. Nobody knows what the hell all those components are, and neither 442 does anybody care anymore. You paved your way to oblivion with buzzwords. 443 Great marketing strategy for gaining more visibility! 444 445Then the next generation KDE arrived, _Plasma 5_. When I was force-migrated to 446it at work with the _SUSE Tumbleweed_ rolling release, the experience was so 447bad that I moved to the _Xfce_ Desktop. 448 449Now every time I started my own KDirStat, it started about a dozen KDE 450processes along with it -- processes that it needs only for minor things like 451loading icons or translations. I really don't need or want that. 452 453So it was time to make KDirStat self-sufficient; it never used that much of all 454the KDE infrastructure anyway. Time to make a pure Qt-based and self-sufficient 455QDirStat. 456 457And while I was at it, I took the chance to add some features that I had wanted 458for a long time, yet I had never gotten myself to start working on: 459 460- Multi-selection in the directory tree so you can delete several files at 461 once. 462 463- Remove limitations like having only a fixed number of user-defined cleanup 464 actions. 465 466- Properly show the output of cleanup actions, in particular when they reported 467 errors. 468 469- Make treemap colors configurable: Use custom colors and match them to 470 user-defined filename extensions. 471 472- Move away from the arcane KDE build system: Back with KDE 1/2/3 it was the 473 _Autotools_ with custom KDE extensions that only a handful people in the 474 world really understood (I was not among them), later _CMake_ which is little 475 better, just differently confusing. 476 477Yes, there is a Qt4 / Qt5 port of KDirStat called K4DirStat. K4DirStat is an 478independent project that started when I had not worked on the old KDirStat for 479a long time (my last KDirStat release had been in mid-2006). 480 481QDirStat is based on that same code from the 2006 KDirStat. It's an 80% rewrite 482using a lot of newer Qt technologies. And there was a lot of cleaning up that 483old code base that had been long overdue. 484 485 486 487## Features 488 489### New Features 490 491- Multi-selection: 492 493 - Both views (the tree and the treemap) now support _extended_ selection, 494 i.e. you can select more than one item. This was the most requested feature 495 for the last KDirStat. Now you can select more than one item at the same 496 time to move it to the trash can, to directly delete it or whatever. 497 498 - Tree view: 499 - Shift-click: Select a range of items. 500 - Ctrl-Click: Select an additional item or deselect a selected one. 501 502 - Treemap: 503 - Ctrl-Click: Select an additional item or deselect a selected one. 504 505 - The current item is highlighted with a red rectangle, all other selected 506 ones with a yellow rectangle. If the current item is not also selected, 507 it has a dotted red outline. 508 509- Proper output of cleanup actions with different colors for the commands that 510 are executed, for their output and for error messages (see screenshot 511 above). That output window can be configured to always open, to open after a 512 certain (configurable) timeout, or only if there are error mesages -- or not 513 at all, of course. If things go wrong, you can kill the external command 514 started by the cleanup action from there. You can zoom in and out (increase 515 or decrease the font size) as you like. 516 517- File type statistics window. WinDirStat has it, and users wanted it in 518 QDirStat, too. Since filename extensions (suffixes) don't have as much 519 semantics in Linux/Unix systems as they do in Windows, many files are 520 categorized as "Other". This is a known limitation, but it's a limitation of 521 the whole concept of using suffixes to categorize files by type. And no, 522 checking file headers for magic byte sequences like the "file" command does 523 is not an option here; QDirStat would have to do that for (at least) all the 524 30,000+ files typically listed under the "Other" category. So we'll have to 525 live with that limitation. 526 527- Locate files by file type window. If you double-click on any of the filename 528 extensions (suffixes) in the file type statistics window, you will get 529 another window that lists all the directories that contain files of that type 530 including the number and total size of those files. You can double-click each 531 of those lines, and that directory will open in the main window with the 532 files of that type preselected so you can start cleanup actions like moving 533 them to trash or converting them to a better format (.bmp -> .png) 534 immediately. 535 536- File size statistics window with histogram, percentiles, buckets and a lot of 537 documentation that everybody should be able to understand. Even if (or, 538 better yet, in particular if) your math teacher or statistics professor never 539 explained it properly, please have a look at it. 540 541- File age statistics window: This lists the number and total size of changed 542 files by years and for recent (13-24) months. You can see in what time frame 543 there was any activity (i.e. any changes) in a directory tree, i.e. when it 544 last was in active use; or if it might be a good candidate to be moved to 545 archive media. 546 547- Packages view: Show installed packages and their files in the tree. Supported 548 for all Linux distributions using any of _dpkg_, _rpm_, _pacman_ as their 549 low-level package manager or any higher-level package manager like _apt_, 550 _zypper_ etc.; more details at [Pkg-View.md](doc/Pkg-View.md). 551 552- Unpackaged files view: Show a directory tree, but ignore all files that 553 belong to an installed software package. Those ignored files are displayed in 554 a special branch _<Ignored>_ in the tree view, and they are not displayed at 555 all in the treemap. This is useful to find files that were manually 556 installed by a `sudo make install` command. More details at 557 [Unpkg-View.md](doc/Unpkg-View.md). 558 559- New macros to use in cleanup actions: 560 561 - %d : Directory name with full path. For directories, this is the same as 562 %p. For files, this is their parent directory's %p. 563 564 - %terminal : Terminal window application of the current desktop; one of 565 "konsole", "gnome-terminal", "xfce4-terminal", "lxterminal", "eterm". 566 The fallback is "xterm". 567 568 - %filemanager : File manager application of the current desktop; one of 569 "konqueror", "nautilus", "thunar", "pcmanfm". The fallback is "xdg-open". 570 571- Which desktop is used is determined by the _$XDG_CURRENT_DESKTOP_ environment 572 variable. Users can override this with the _$QDIRSTAT_DESKTOP_ environment 573 variable, so you can get, say, the Xfce terminal or file manager despite 574 currently running KDE if you set 575 576 export QDIRSTAT_DESKTOP="Xfce" 577 578- Of course, you can still simply use your favourite file manager if you simply 579 change %filemanager in the default "Open File Manager Here" cleanup action to 580 the command to start it. 581 582- You can now select the shell to use for the cleanup commands: 583 584 - $SHELL (the user's login shell) - using the same environment, syntax and 585 wildcard etc. behaviour of the shell the user is used to. 586 - /bin/bash for well-defined behaviour for wildcards etc. 587 - /bin/sh as a last resort (which might be a simplistic _dash_ on Ubuntu). 588 589- Mouse actions in the treemap window: 590 591 - Left click: Select item and make it the current item. 592 - Right click: Open the context menu with cleanup actions and more. 593 - Ctrl+Left click: Add item to selection or toggle selection. 594 - Middle click: Select the current item's parent. Cycle back at toplevel. 595 - Double click left: Zoom treemap in. 596 - Double click middle: Zoom treemap out. 597 - Mouse wheel: Zoom treemap in or out. 598 599- You can configure what columns to display in the tree view and in which 600 order. The only thing that is fixed is the "Name" column which is always 601 there and always the first (leftmost). Use the context menu in the tree 602 header to unlock column widths. Drag columns to the left or right to change 603 their order. 604 605- Exclude rules are now greatly simplified. They no longer always get the 606 entire path to match which requires quite complex regexps; by default, they 607 only get the last path component -- i.e., no longer 608 "/work/home/sh/src/qdirstat/src/.git", but only ".git". You can now even tell 609 the exclude rule to use a simplified syntax: "FixedString" or "Wildcard" in 610 addition to the normal "RegExp". The old behaviour (matching against the full 611 path) is still available, though. 612 613- Configuration dialog for exclude rules -- see screenshots. 614 615- Subvolume detection for Btrfs. Btrfs subvolumes are just ordinary mount 616 points, so normally QDirStat would stop scanning there, leaving a large part 617 of a Btrfs partition unaccounted for. But for each mount point found while 618 scanning a directory tree, QDirStat checks /proc/mounts or /etc/mtab if it 619 has the same device name as its parent directory, and if yes, considers it a 620 subvolume and continues scanning. 621 622- Actions to go one directory level higher or to the toplevel: Context menu and 623 menu "Go To" -> "Up One Level" or "Toplevel". This is useful if you clicked 624 on a file in the treemap that is deep down in some subdirectory, and you want 625 to know what subdirectory that is: Simply click "Go Up" twice (the first 626 click will get you to the <Files> pseudo subdirectory, the second one to the 627 real one). 628 629- Open all tree branches up to a certain level and close all other ones: Menu 630 "View" -> "Expand Tree To Level" -> "Level 0" ... "Level 9". 631 632- The total sum of the selected items (subtrees) is displayed in the status 633 line if more than one item is selected. 634 635- Icons are now compiled into the source thanks to Qt's resource system; now 636 it's just one binary file, and nothing will go missing. No more dozens of 637 little files to handle. 638 639- The build system is now Qt's _QMake_. I got rid of that _AutoTools_ 640 (Automake, Autoconf, Libtool) stuff that most developers find intimidating 641 with its crude M4 macro processor syntax. QMake .pro files are so much 642 simpler, and they do the job just as well. And no, it will definitely never 643 be _CMake_: I don't like that thing at all. It's just as much as a PITA as 644 the AutoTools, just not as portable, no usable documentation, it's changing 645 all the time, and those out-of-source builds are a royal PITA all on their 646 own with constantly having to change back and forth between source and build 647 directories. 648 649- QDirStat now has its own log file. It now logs to 650 `/tmp/qdirstat-$USER/qdirstat.log` (where $USER is your Linux user name). 651 No more messages on stdout that either clobber the shell you started the 652 program from or that simply go missing. 653 654- No longer depending on dozens of KDE libs and a lot of KDE infrastructure; it 655 now only requires Qt which is typically installed anyway on a Linux / BSD / 656 Unix machine with any X11 (graphical) desktop. 657 658- It should still compile and work with Qt4. We now have a contributor who is 659 very interested in that (Michael Matz), so it should be possible to maintain 660 this compatibility. 661 662- Slow down display update from 333 millisec (default) to 3 sec (default) with 663 `qdirstat --slow-update` or `qdirstat -s`. The slow update interval can be 664 customized in `~/.config/QDirStat/QDirStat.conf`: 665 666 ```ini 667 [DirectoryTree] 668 SlowUpdateMillisec = 3000 669 ``` 670 671 672 673### Old Features 674 675Features ported from the old KDirStat: 676 677- Fast and efficient directory reading. 678 679- Not crossing filesystem boundaries by default so you can see what eats up 680 all the disk space on your root filesystem without getting distorted numbers 681 due to all the other filesystems that are mounted there. If you absolutely 682 wish, you can use "Continue reading at mount point" from the context menu or 683 from the "File" menu -- or configure QDirStat to always read across file 684 systems. 685 686- Efficent memory usage. A modern Linux root filesystem has well over 800,000 687 objects (files, directories, symlinks, ...) and about 100,000 directories. 688 This calls for minimalistic C++ objects to represent each one of 689 them. QDirStat / KDirStat do their best to minimize that memory footprint. 690 691- Hierarchical tree view that displays accumulated sums in each branch, 692 together with a percent bar so you can see at a glimpse how the 693 subdirectories compare with each other. 694 695- All numbers displayed human readable -- e.g., 34.4 MB instead of 36116381 696 Bytes. 697 698- All size units are 1024-based, i.e. 1 kB = 1024 Bytes; 1 MB = 1024 kB; 1 GB = 699 1024 MB. 700 701- In the tree, also displaying the exact byte size as the context menu (right 702 click). 703 704- Each tree level uses another color for that percent bar so you can easily 705 compare subdirectories even if some of them are opened in the tree. 706 707- If a directory has files and subdirectories, all files in that subdirectory 708 are grouped into a <Files> pseudo directory (called _dot entry_ in the 709 QDirStat sources) so you can compare the disk usage of files on that 710 directory level with the subdirectories. 711 712- Displaying the latest modification time of any object in each branch. You can 713 instantly see in what subdirectory where any changes lately. You can sort by 714 this column, of course. 715 716- Treemap display. Treemaps are a way to visualize hierarchical data 717 structures, invented by Ben Shneiderman. Basically, the hierarchy is 718 flattened and each level grouped in a rectangle, inside which it is again 719 subdivided in rectangles. The area of each rectangle corresponds to the size 720 of each item or subdirectory. For the purposes of QDirStat, it is enough to 721 know that a large blob corresponds to a large file; you can instantly see 722 where large ISOs or movies are. 723 724- You can zoom the treemap in and out (Ctrl + / Ctrl - / mouse wheel / menu / 725 tool bar) to see more details of directories that are otherwise dominated by 726 larger ones. 727 728- You can move the boundary between treemap and tree view up and down as you 729 like. You can also get rid of the treemap completely (menu "Treemap" -> "Show 730 Treemap" or F9 key) 731 732- Treemap and tree list view communicate. Select an item in one view, and it is 733 also selected in the other. If you click on that large blob in the treemap, 734 it is located in the tree view, all branches up to its directory are opened, 735 and the tree view scrolls to that item. 736 737- Cleanup actions. Once you know what is consuming the disk space, you can 738 start cleanup actions from within QDirStat to reclaim disk space - or to 739 investigate further if you can safely delete a file. You can create your own 740 cleanup actions (as many as you like), and there are some predefined ones: 741 742 - Open file manager here. This will start a file manager in the directory of 743 the current item. QDirStat tries its best to guess the name of the relevant 744 file manager application for the current desktop, based on the 745 $XDG_CURRENT_DESKTOP environment variable. You can override this with the 746 $QDIRSTAT_DESKTOP environment variable. 747 748 - Open terminal window here. In most cases, this is much easier than to 749 navigate to that directory with 'cd' in an already open terminal window and 750 using tab-completion numerous times. As with the file manager application, 751 QDirStat tries its best to guess the name of the relevant terminal window 752 application for the current desktop. 753 754 - Move to trash bin. QDirStat has its own implementation of the XDG trash 755 specification. 756 757 - Delete immediately. 758 759 - Compress: Create a compressed tar archive from a directory and then delete 760 the directory. 761 762 - Delete junk files: Backup files left behind by editors, core dumps. 763 764 - All predefined cleanup actions are fully configurable, of course. You can 765 change any of them, disable them, or delete them. 766 767- You can copy the complete path of the selected file or directory to the 768 system clipboard and paste it to another application. 769 770- Reading and writing cache files: 771 772 - This is mostly meant for remote servers in some server room somewhere: 773 Rather than installing the Qt and X11 runtime environment and running 774 QDirStat over remote X (ssh with X forwarding), you can run the supplied 775 _qdirstat-cache-writer_ Perl script on the server, copy the resulting cache 776 file to your desktop machine and view the content there with QDirStat. 777 778 - For large directories (archives etc.) that don't change that much, you can 779 also generate a QDirStat cache file (either with the Perl script or with 780 QDirStat itself) and save it to that corresponding directory. If QDirStat 781 finds a file .qdirstat.cache.gz in a directory, it checks if the toplevel 782 directory in that cache file is the same as the current directory, and if 783 it is, it uses the cache file for that directory rather than reading all 784 subdirectories from disk. If you or the users of that machine use QDirStat 785 often, this might take a lot of I/O load from the server. 786 787 - If you use the '-l' option of the qdirstat-cache-writer script, it uses the 788 long file format with a complete path for each entry, so you can use the 789 _zgrep_ command with it as a replacement for the _locate_ command. 790 791 - The KDirStat / QDirStat file format is well documented and very simple. It 792 seems to be used by a number of admins and some backup software. 793 See also the specification in the doc/ directory: 794 https://github.com/shundhammer/qdirstat/blob/master/doc/cache-file-format.txt 795 796 - You can specify a cache file to read directly at the command line: 797 798 ``` 799 qdirstat --cache cache-file 800 ``` 801 802- Other command line options: See 803 ``` 804 qdirstat --help 805 ``` 806 807 808### Features that are Gone 809 810(Compared to the old KDirStat) 811 812- Pacman animation 813- KIO slave support 814- Feedback form 815 816<details> 817 818- KPacman: That was that PacMan animation wile reading directory reading. This 819 is gone now. KPacMan looked out of place pretty soon after it got to KDirStat 820 due to Qt styles doing fancy rendering of widget backgrounds with gradients 821 etc. I know that it does have its fans, but it's unrealistic to get this 822 back without breaking the menu bar rendering. 823 824- KioDirReadJob: Network-transparent directory reading for network protocols 825 like FTP, HTTP, Fish (ssh-based). This depended on KDE's KIO slaves, so this 826 functionality is gone now without KDE. That's a pity, but this is a little 827 price to be paid to avoid the rest of the hassle with using the KDE libs. 828 829- KFeedback: That was that form where users could tell their opinion about 830 KDirstat. But that was not used that often anyway - not nearly enough to 831 justify the effort that has gone into that part. And the KDE usability 832 people, like usability people generally tend to do, first discussed that to 833 death and then decided they didn't want anything like that in general in KDE 834 applications. So be it. 835 836- KActivityTracker: That was a supporting class for KFeedback that kept track 837 of how much a user was using the program and after a while (when it was 838 determined that it made sense) asked if the user wouldn't like to give his 839 feedback about the program. 840 Don't you all just hate those dumbass web designers who tell you to do a 841 survey how much you like their grand web page before you even had a chance to 842 look at it? Shove a pop-up up your face covering the stuff you are 843 interesting in with their self-loving marketing bullshit? -- KActivityTracker 844 was made to avoid exactly this: Ask the user only once you know that he 845 actually used the program for a while. 846 847</details> 848 849 850 851## MacOS X Compatibility 852 853<summary> 854There is some experimental support for MacOS X, but it's really only that: Experimental. 855</summary> 856<details> 857 858I was amazed to find that it doesn't take more than the normal "qmake" and then 859"make" to build QDirStat for MacOS X. We (Sonja Krause-Harder and I) did some 860basic testing, and it seems to work. 861 862The cleanups may need some adaptation, but this is something that might even be 863configured by the user. 864 865If anybody wants to give it a try, download Qt for MacOS X, install it, open a 866shell window, search the _qmake_ command: 867 868 find . -name qmake 869 870Add this to your $PATH, then do the normal 871 872 qmake 873 make 874 875Not sure how well "make install" works, though. 876 877**_Be advised that QDirStat on MacOS X is purely experimental at this stage._** 878 879There is no support. If you try this, you are on your own. Even more so than 880with the other platforms, you will have to make sure that your Qt build 881environment is set up correctly. 882 883</details> 884 885_There be dragons._ ;-) 886 887 888### Architecture maintainer wanted for QDirStat for MacOS X 889 890If you are a developer with some prior C++ and Qt knowledge on the MacOS X 891platform and you'd like to see QDirStat working there, please consider joining 892the team. 893 894 895## Windows Compatibility 896 897There is no native Windows version, but you can use the 898[docker](#qdirstat-docker-container) container. 899Other than that, there is [WinDirStat](https://windirstat.info/). 900 901<details> 902There are currently no plans for doing a native Windows port. 903 904Directory reading might be quite easy to replace for Windows; we don't have 905that problem with devices and crossing filesystems on that platform. 906 907But the cleanups might be a challenge, "move to trash" works completely 908differently, and we'd need an installer for a Windows version. 909 910So, for the time being, use the [docker](#qdirstat-docker-container) or 911[WinDirStat](https://windirstat.info/) instead. 912 913WinDirStat is a close relative to the KDirStat family anyway; the author had 914liked KDirStat on Linux so much that he decided to write a Windows clone and 915called it WinDirStat. 916</details> 917 918 919## Ready-made Packages 920 921[![Packaging status](https://repology.org/badge/tiny-repos/qdirstat.svg)](https://repology.org/metapackage/qdirstat/versions) 922 923 924### openSUSE / SUSE Linux Enterprise 925 926QDirStat packages for openSUSE Tumbleweed / Leap (15.x, 42.x) and SLE (15, 12): 927 928- Download page for the [**latest stable release**](https://software.opensuse.org/download/package?project=home:shundhammer:qdirstat-stable&package=qdirstat) 929 930- Download page for the [**current development version** (git master)](https://software.opensuse.org/download/package?project=home:shundhammer:qdirstat-git&package=qdirstat) 931 932 Since this version is in development, it may be not quite as stable and 933 reliable as the latest official stable release, although the QDirStat 934 developers try their best to keep it as stable as possible. 935 936 937### Ubuntu 938 939https://packages.ubuntu.com/search?keywords=qdirstat&searchon=names 940 941 942### Debian 943 944https://packages.debian.org/search?keywords=qdirstat 945 946 947### Fedora 948 949https://apps.fedoraproject.org/packages/qdirstat/builds/ 950 951 952## QDirStat Docker Container 953 954@jlesage kindly provides a 955[docker container for QDirStat](https://hub.docker.com/r/jlesage/qdirstat). 956 957That makes QDirStat usable even on non-Linux / non-Unix systems such as Windows 958or MacOS X. 959 960Docker is basically a virtualized environment to run software that was designed 961for a different operating system. 962 963It is very much like using VmWare or VirtualBox, but with much less overhead: 964You don't have to install that other system first and then on top of that the 965application that you really want to run. A docker container contains everything 966that is needed, and it is preconfigured for that application. 967 968 969### How to use Docker on Windows 970 971- Download and install [Docker Desktop for Windows](https://hub.docker.com/editions/community/docker-ce-desktop-windows) 972- Use the Docker Desktop for Windows to launch the 973[QDirStat Docker](https://hub.docker.com/r/jlesage/qdirstat) (as a Linux container) 974- Adapt the command line so the disk that you want to explore is used 975 976More information: 977 978- https://docs.docker.com/docker-for-windows/install/ 979- https://docs.docker.com/get-started/ 980 981 982 983## Building 984 985_Notice that for most mainstream Linux or BSD distributions you don't have to 986build your own; you can simply install a ready-made package from your normal 987package manager._ 988 989 990### Build Environment 991 992Make sure you have a working Qt 5 build environment installed. This includes: 993 994- C++ compiler (gcc recommended) 995- Qt 5 runtime environment 996- Qt 5 header files 997- libz (compression lib) runtime and header file 998 999If anything doesn't work, first of all **make sure you can build any of the 1000simple examples supplied with Qt**, e.g. the 1001[calculator example](http://doc.qt.io/qt-5/qtwidgets-widgets-calculator-example.html). 1002 1003 1004#### Ubuntu 1005 1006Install the required packages for building: 1007 1008 sudo apt-get install build-essential qtbase5-dev zlib1g-dev 1009 1010Dependent packages will be added automatically. 1011 1012Recommended packages for developers: 1013 1014 sudo apt-get install qttools5-dev-tools qtbase5-doc qtbase5-doc-html qtbase5-examples 1015 1016See also 1017 1018http://askubuntu.com/questions/508503/whats-the-development-package-for-qt5-in-14-04 1019 1020If you also have a Qt4 development environment installed, select the desired 1021one via _qtchooser_: 1022 1023 sudo apt-get install qtchooser 1024 export QT_SELECT="qt5" 1025 1026 1027#### SUSE 1028 1029Install the required packages for building: 1030 1031 sudo zypper install -t pattern devel_C_C++ 1032 sudo zypper install libQt5Widgets-devel libqt5-qttools zlib-devel 1033 1034If you also have a Qt4 development environment installed, make sure that the 1035Qt5 version of 'qmake' is the first in your $PATH: 1036 1037 export PATH=/usr/lib64/qt5/bin:$PATH 1038 1039 1040### Compiling 1041 1042Open a shell window, go to the QDirStat source directory, then enter these 1043commands: 1044 1045 qmake 1046 make 1047 1048 1049### Installing 1050 1051 sudo make install 1052 1053or 1054 1055 su -c make install 1056 1057 1058### Install to a Custom Directory 1059 1060The default setup installs everything to `/usr`. To install to another 1061directory, set `INSTALL_PREFIX` during `qmake`. 1062 1063<details> 1064 1065 qmake INSTALL_PREFIX=/usr/local 1066 1067Beware that some things might not work as expected; for example, you will not 1068get a `.desktop` file in the proper place to make QDirStat appear in any menus 1069in your graphical desktop environment or in the file manager. You will need to 1070copy the `.desktop` file manually to whatever directory your graphical desktop 1071environment uses somewhere in your home directory. Similar with the application 1072icon used in that `.desktop` file. 1073</details> 1074 1075 1076## Contributing 1077 1078See file [Contributing.md](doc/Contributing.md) 1079and [GitHub-Workflow.md](doc/GitHub-Workflow.md) 1080 1081 1082## Troubleshooting 1083 1084### Can't Move a Directory to Trash 1085 1086See file [Troubleshooting.md](doc/Troubleshooting.md) 1087 1088 1089## Further Reading 1090 1091- Original [KDirStat](http://kdirstat.sourceforge.net/) ([source code](https://github.com/shundhammer/kdirstat)) 1092- [K4Dirstat](https://bitbucket.org/jeromerobert/k4dirstat/wiki/Home) ([source code](https://bitbucket.org/jeromerobert/k4dirstat/src)) 1093- [WinDirStat](https://windirstat.info/) (for Windows) 1094- [Disk Usage Tools Compared: QDirStat vs. K4DirStat vs. Baobab vs. Filelight vs. ncdu](https://github.com/shundhammer/qdirstat/wiki/disk-usage-tools-compared) (including benchmarks) 1095- [XDG Trash Spec](http://standards.freedesktop.org/trash-spec/trashspec-1.0.html) 1096- [Spatry's QDirStat Review on YouTube](https://www.youtube.com/watch?v=ysm4-x_5ftI) 1097 1098Of course, don't forget to check out the [doc directory](doc/). 1099 1100 1101## Packaging Status 1102 1103Repology: QDirStat versions in Linux / BSD distributions: 1104 1105[![Repology](https://repology.org/badge/tiny-repos/qdirstat.svg)](https://repology.org/metapackage/qdirstat/versions) 1106 1107(click for details) 1108 1109 1110## Donate 1111 1112QDirStat is Free Open Source Software. 1113 1114If you find it useful, please consider donating. 1115You can donate any amount of your choice via PayPal: 1116 1117[![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=EYJXAVLGNRR5W) 1118