gentoo(1x)

📦 version 0.20.7, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🦋 gentoo(1x) — the file manager that's literally the moment 🦋

okay bestie, sit down, hydrate, because I'm about to introduce you to gentoo, and it's giving main character energy for your whole filesystem. this is gentoo(1x), the X file manager, and yes it's a real one and yes it slays. 💅

✨ NAME ✨

gentoo — a highly configurable file manager for X 🌸

✨ SYNOPSIS ✨

gentoo [--version] [--locale-info] [--root-ok] [--no-rc] [--no-gtkrc]
[--no-dir-history] [--left=path] [--right=path] [--run=ARG]

that's the whole vibe check, fr fr. 🫶

✨ DESCRIPTION ✨

okay so. gentoo is a file manager for Linux and compatible systems. it lets you interactively navigate your file system using the mouse, and also do a bunch of pretty standard operations on the files and directories in there — copy, move, rename, the whole ✨suite✨. ngl, it's a lot.

here's the iconic part: gentoo always shows you the contents of two directories at once. each one lives in its own scrollable list called a pane. at any single moment, exactly one pane is the current pane, and you can spot it because it has a highlighted bar running across its top region. the current pane is the source for every file operation, and the other pane is the destination. you can select rows in panes using selection methods of varying complexity — and bestie, "varying complexity" is doing some heavy lifting there, because it goes from simply clicking a row all the way to selecting rows by name using a regular expression. once you've got a selection, you click a button and boom, the command happens on your selected files. 🎀

all file operations performed by gentoo are implemented natively. like, when you use gentoo to copy a file, gentoo does not just go run the system's cp(1L) command. no ma'am. gentoo has its own code for opening source and destination files and then reading and writing the right amount of data between them. the way this works is that it makes gentoo independent of whether shell commands are even available to do stuff. lowkey genius. 😭

gentoo also incorporates a fairly powerful, object-oriented file typing and styling system. it can use a variety of ways to figure out the type of the files it's displaying. each type is then linked to something called a style, and that style controls how rows of that type get rendered in panes. you can use this whole system to control icons, colors, and various operations on the rows. for example — and this is the flex — it's easy to make gentoo display all PNG images in red, and to invoke The GIMP(1) on them when they're double-clicked. obsessed. 🔥

a design goal with gentoo has been to provide full GUI configurability, removing the need to edit a configuration file by hand and restart the program just to see the changes — which is, unfortunately, otherwise common in many programs for Un*x. because of that, gentoo has a Configuration dialog window where you can configure most aspects of its operation directly, using the mouse and standard GUI widgets. no .conf-crying required. 💖

and for the lore girlies: gentoo borrows its basic look'n'feel from the classic Amiga file manager Directory OPUS — but it is not a "clone" of any kind. it's its own person. periodt. 👑

✨ OPTIONS ✨

gentoo is not primarily driven by command line arguments, but these ones are available, and they're cute:

  • --version — causes gentoo to print its version number to the standard output, and then exit successfully. the version number is a string of the form MAJOR.MINOR.MICRO, like 0.20.7. numbers having an odd MINOR component indicate development versions of the program. and so far, all versions of gentoo have been classified as being development versions. 💀
  • --locale-info — makes gentoo print a couple of localization settings, and then exit. this is mostly useful during development and debugging, and not of a lot of interest when you're just using the application. (iykyk, otherwise skip it 💅)
  • --root-ok — makes gentoo accept being run by the root user. normally this is not allowed, since it's considered a big threat to system security. note that gentoo has the ability to execute user-defined strings using the execvp(3) function, and this is generally considered harmful.
bestie. listen. if you really want to run gentoo while logged on as root, supplying this option allows you to. it is not recommended, though. 🙈
  • --no-rc — starts up gentoo without loading any configuration file. this makes it run using the built-in defaults, which are very Spartan indeed. seldom comfortable, but occasionally handy when you're trying to determine if a problem is with the configuration or with the core code. it's giving "diagnostic era". 🧚
  • --no-gtkrc — avoids loading the GTK+ RC file, which disables any widget customizations, and forces all widgets to use the default GTK+ look. back to basics, babe. 🌈
  • --no-dir-history — avoids loading the file that holds the history, i.e. which directories have been previously visited by the two panes. very rarely needed, included mostly for completeness' sake. ⭐
  • --left, --right (or -1, -2) — sets the initial path for the left and right pane, respectively. if present, the path specified with one of these options overrides any other path for the pane in question. see below (Initial Directory Paths) for details. 👀
  • --run ARG (or -rARG) — runs ARG, a gentoo command. commands specified this way are executed before gentoo accepts any user input through the graphical interface, but after the configuration file has been read in. you can use it many times in order to make gentoo run a whole series of commands. remember that gentoo's command names are case-sensitive, and that built-in commands (like "About") always begin with a capital letter. 🔥

any non-option command arguments will be silently ignored. 💀

if an argument -h or --help is given, gentoo will give a summary of its supported command line options and exit successfully. 🫶

if an unknown option is given, or an option is missing a required argument, gentoo will whine and exit with a failure. as it should, honestly.

💖 BASIC USAGE 💖

So like, when gentoo boots up it opens its one (1) main window, and that window is split vertically down the middle (or horizontally, bestie — it's configurable 💅) which makes the two panes we were just talking about. And down at the bottom? A whole bank of buttons. Iconic layout honestly.

🎀 Initial Directory Paths 🎀

The actual paths that show up in the two panes when you start up? You can steer those in a bunch of different ways. There are four ways a path can end up showing in a pane, and here they are in order of decreasing priority:

  1. Command-line Argument Using the --left and --right arguments (or their short forms, -1 and -2) overrides literally every other setting. No cap.
  2. Configured Default Directory If there's no command-line argument and the "Default Directory" configuration option is set, then that directory is the one that gets used.
  3. Most Recently Visited Directory If there's no default directory, the most recently visited directory gets pulled from the directory history for each pane. Lowkey this only works if a directory history file has actually been found and loaded, so like… no history file, no dice.
  4. Current Directory If all else fails? gentoo just uses the current directory ("."). The humble fallback. 🫶

Navigating the file system in gentoo is genuinely so simple. The two panes act as independent views of the file system, and you navigate both of them in exactly the same way.

You can always tell which directory a pane is showing by reading its path, which is displayed in the entry box below the pane (by default, anyway — you can change the position to above if that's more your vibe).

To enter a directory, find it in the pane and double click it with the left mouse button. gentoo reads the directory's contents and updates the display accordingly. Slay.

There are several ways of going up in the directory structure. To enter the directory containing the one currently shown (aka the current dir's parent), you can:

  • click the parent button (it's to the left of the path entry box)
  • hit Backspace on your keyboard
  • click the middle mouse button
  • select "Parent" from the pop-up menu you get on the right mouse button
  • or click the downward arrow to the right of the path box — that pops up the directory history menu — and then select the second row from the top

Five options, all valid, pick your fighter. ✨

🌸 Selecting Files 🌸

Before you can do literally anything to a file, you gotta select it. Every single file-management command in gentoo acts upon the current selection (in the current pane). There are several ways of selecting files, but the most frequently used ones are mouse-based. And just a heads up: the word "file" below really should be read as "file or directory", because selection does not distinguish between the two.

To select a file (or directory), just point the mouse at the name — anywhere in the row is fine — and click the left mouse button. The colors of the clicked row will change, which tells you it's currently selected. To select more rows, keep the mouse button held down and drag the mouse vertically. gentoo extends the selection, including every row you touched. And if you drag across the top or bottom border, the pane will scroll, trying to keep up with you. This is a very quick and convenient way of selecting multiple files, as long as they're listed in succession. Chef's kiss.

If you click again on a file that's already selected, you'll unselect it. And you can drag to unselect several files, exactly like when selecting.

To select a sequence of files without dragging: first click normally on the first file you wanna select. Then release the mouse button, locate the last file in the sequence (it can be either above or below the first one), hold down shift on your keyboard, and click that file. gentoo now adds all the files between the first and the last to the current selection. Periodt.

Now — if you follow those exact same steps to select a sequence, but you press control instead of shift before clicking the second time, gentoo will unselect the range of files indicated. Reverse uno. 🙈

If you click on a file with the meta key held down (that's actually a key labeled Alt, located to the immediate left of the space bar, on my PC keyboard), gentoo does something genuinely cool: it will select (or unselect — it's a toggle, just like ordinary selection) all files, including the clicked one, that have the same type as the one you clicked. This can be used to select, for example, all PNG image files in a directory even if you can only see one of them. Occasionally very useful. 👑

And if you click on a file with both shift and control held down, gentoo will toggle the selected state of all files having the same file name extension as the one you clicked. This can sometimes be useful to select files that you don't have a proper type defined for — as long as those files do share an extension, that is. iykyk.

💜 Changing Sort Order 💜

The files and directories listed in each of gentoo's two panes are always sorted on some column — typically file name. You can choose to sort on some other field by clicking the appropriate column title once. And if you click on the field that's already current, the sorting gets reversed (so for names it'll be Z-A rather than A-Z).

If your display includes icons, try sorting on that column: gentoo will then order each row according to its File Style, grouping the rows based on their parent styles, all the way up to the root of the Style tree. Which means, for example, that JPEG and PNG pictures (both having an immediate parent style of Image) will be shown together, and before all Text files (HTML, man pages and so on). It's quite cool, really. :)

💅 Executing Commands 💅

Commands are how you make gentoo do stuff. The typical command operates upon the set of selected files in the current pane, so it's usually a good idea to first select some files (see the previous subsection for the details on that). Once you've got a bunch of files selected, you need to tell gentoo which command to execute. There are several ways of doing this.

Most basic file operations (e.g. copy, move, rename, and so on) live on the — cleverly labeled — buttons along the bottom of gentoo's main window. To copy a file, just select it, then click the button labeled "Copy". It's really that simple. Most of these built-in (or native) commands automatically operate recursively on directories, so you could copy (or move) a whole directory of files by just selecting it and then clicking "Copy". 🎀

If you can't see a button that does the thing you wanna do, there's a chance the command exists but just isn't bound. Click the right mouse button in a pane — this opens up the "pane pop-up menu". Select the "Run..." item. This opens up a dialog window showing all available commands. Select a command, and click "OK" to execute it. Easy.

⭐ CONFIGURATION ⭐

gentoo is a pretty complicated program, ngl — it has a rather large amount of configuration data it needs in order to be really useful. For example, my current personal configuration file contains well over a thousand different configuration values. 😭 A thousand!! She's high maintenance and we love her for it.

To store this hefty amount of configuration data, gentoo uses a heavily structured configuration file. In fact, the file is (or at least it should be) legal XML! Yes bestie, it's XML. Breathe.

When new features get added to gentoo, they'll typically require some form of configuration data, and that data is then simply added somewhere in the existing configuration file structure. Effort is made to assign reasonable built-in default values for all such new features, so older configuration files (that don't contain the values required by the new features) should still work. 🫶 And the first time you hit "Save" in the configuration window after changing your version of gentoo, your personal configuration file will be updated to match the version of gentoo you're running. Self-healing config, we stan.

Describing how to go about configuring gentoo is too big a topic for a manual page to cover. I'll just say that the command to open up the configuration window is called "Configure". It's by default available on a button (typically the top-right one), in the pane pop-up menu, and also by pressing the C key on your keyboard. Three ways in, go wild.

🌈 FILES 🌈

  • ~/.config/gentoo/gentoorc — A user's personal configuration file. When gentoo starts up, it will try to load this file. If the file isn't found, the old name ~/.gentoorc is tested, and if that also fails, a site-wide configuration (see below) will be tried instead.
  • /etc/gentoorc — This is the site-wide configuration file. If a user doesn't have a configuration in his/her home directory, gentoo loads this file instead. The actual location of this file is slightly system-dependent — the above is the default. As an end user, you typically won't need to access this file manually.
  • ~/.config/gentoo/dirhistory — This file contains lists of the most recently visited directories, for both panes. These are the lists that appear in the drop-down menu when the arrow next to the path entry box is clicked. Can be disabled in the Dir Pane configuration.
  • ~/.config/gentoo/gtkrc — This file allows you to control the look of the widgets used by gentoo, through the GTK+ style system. You can change the actual path in gentoo's Configuration window; the above is the typical default for a modern Linux-based system. If a file named gtkrc is not found in the configured path, the names gentoogtkrc and .gentoogtkrc (note the period), in that order, are also tested.
  • /etc/passwd, /etc/group — These two files normally hold the system's password and group information. These are (probably) the ones gentoo uses to map user IDs to login names, to do tilde-expansion (mapping of user name to directory path), and to map group IDs to group names. That is probably, because gentoo doesn't actually refer to these files by name. Instead, it uses the (BSD-style) API function calls getpwent(3) and getgrent(3) to access this information.
  • /etc/fstab, /proc/mounts, (or /etc/mtab) — These files contain data on available and mounted file systems. They are read by gentoo's auto-mounting code. You can configure the exact file names used, on the "Mounting" tab in the main configuration window.
Heads up bestie: using /proc/mounts rather than /etc/mtab is recommended on Linux systems. They contain roughly the same data, but the one in /proc is always up to date, and faster to read! 💀🔥

💀 BUGS 💀

okay bestie, listen up, because this part is important. every single gentoo release numbered 0.x.y where x — the so-called minor version number — is odd, is a development release, not a stable one. and that means the software will probably be out here suffering from bugs. it's giving "beta energy" for real. so if you find something you suspect is actually a bug, please don't hesitate to contact the author! deets on how are below. 🫶

and if you're sitting there concerned about using potentially buggy and completely unwarranted software to manage your precious files? bestie, feel free not to use gentoo. the world is full of alternatives. no hard feelings. 💅

the chances that a bug gets fixed increase greatly if you report it. don't just suffer in silence.

when you report a bug, you must describe how to reproduce it, and also try to be as detailed and precise as possible in your description of the actual bug. if possible, maybe include the output of gdb(1) (or whatever your system's debugger is called, iykyk). in some cases it might be helpful to include the configuration file you were using when the problem occurred. and before you report anything, please make sure you're running a reasonably recent version, because otherwise "your" bug might already have been fixed. (see below for how to obtain new releases. ✨)

also — and this is the part everyone skips — you should locate and read through the BUGS file distributed with gentoo, so you don't go through all this hassle just to report an already known bug and waste everybody's time. not the vibe. 🙈

👑 AUTHOR 👑

gentoo was written, from scratch, by Emil Brink. the first line of code was written on May 15th, 1998. it's his first program to use the GTK+ GUI toolkit, his first program to be released under the GPL, and also his first really major Linux application. main character origin story fr fr. 🌈

the only efficient way to contact him (to report bugs, give praise, suggest features/fixes/extensions/whatever) is by Internet e-mail. the address is <emil@obsession.se>. please try and include the word "gentoo" in the Subject part of your e-mail, to help him organize his inbox. thanks. 🎀

if you're really not in the mood for the direct feel of e-mail, the second best choice for reporting bugs and making suggestions is to use the web-based bug tracker at <https://sourceforge.net/p/gentoo/bugs/>. thanks for contributing. 💖

🦋 ACKNOWLEDGMENTS 🦋

the author wishes to thank the following people for their various contributions to gentoo:

  • Johan Hanson (<johan@tiq.com>) — Johan is the man behind all icon graphics in gentoo, and also the author of the custom widgets used in it. he also comes up with plenty of ideas for new features and changes to old ones, some of which are even implemented. Johan has stuff at <http://www.bahnhof.se/~misagon/>. an icon.
  • Jonas Minnberg (<sasq@nightmode.org>) — Jonas did intensive testing of early versions of gentoo, and eventually persuaded Emil into releasing it (back around version 0.9.7 or so). lowkey the reason we're all here. 🔥
  • Ulf Petterson (<ulf@obsession.se>) — Ulf drew the main gentoo logo (the one shown in the About window), and also designed the main HTML documentation's layout. aesthetic king.
  • Josip Rodin (<jrodin@jagor.srce.hr>) — Maintainer of the gentoo package for Debian Linux, and also a source of suggestions for improvements, as well as a relay for bug reports from Debian Linux users.
  • Ryan Weaver (<ryanw@infohwy.com>) — Maintainer of the gentoo packages for Red Hat Linux, and probably one of the fastest package creators out there. :) absolute speedrun legend.
  • Oliver Braun, Jim Geovedi and Pehr Johansson — Maintainers of gentoo ports to FreeBSD, OpenBSD, and NetBSD, respectively. the BSD girlies, we love them. 🐧

thanks also to all people who have mailed Emil about gentoo, providing bug reports, feature requests, and the occasional kind word. :^) it's because of people like yourselves that we have this wonderful computer platform to play with. 💜

gentoo is released as free, open-source software, under the terms of the GNU General Public License (GNU GPL), version 2. this license is included in the distribution under the traditional name of COPYING, and Emil suggests that you read it if you're not familiar with it. if you can't find the file but have Internet access, you could take a look at <http://www.gnu.org/>.

it is important to realize that the mentioned license means that there is ABSOLUTELY NO WARRANTY for this software. like, none. zero. nada. not a single one. 💀

🌸 OTHER INFO 🌸

some unfinished, outdated, but still pretty informative documentation is available, in HTML format, in the docs/ subdirectory in the distribution archive. if you haven't installed gentoo from the original .tar.gz distribution archive, you might need to either inspect the distribution you did use (perhaps it came as some form of "package"), or contact a system administrator. slay, go ask your sysadmin bestie. 🧚

the GTK+ GUI toolkit that gentoo requires is available at <http://www.gtk.org/>. gentoo uses the slightly outdated stable series, called 1.2.x. the latest known release in that series is GTK+ 1.2.10. because of severe performance problems, gentoo will probably not be ported to use the current (2.0.x) series of GTK+ any time soon. ngl it's staying in its lane. 🦋

the latest version of gentoo is always available on the official gentoo home page, at <http://www.obsession.se/gentoo/>. go get it. ⭐

🔍 SEE ALSO 🔍

manual page section numbers in this page refer to sections on (some?) Linux systems — your mileage will most likely vary. try the apropos(1) command, it might help you out. 💅

and that's the whole page, bestie! 🫶 this iconic lil manual is brought to you by Obsession Development, dated June, 2016, and it documents gentoo(1x). read it, love it, report your bugs with gdb output attached, and go manage those precious files. periodt. ✨👑💖

📦 where this page comes from