1gentoo(1x)                                                          gentoo(1x)
2
3
4

NAME

6       gentoo - A highly configurable file manager for X
7

SYNOPSIS

9       gentoo   [--version]   [--root-ok]  [--no-rc]  [--no-gtkrc]  [--no-fam]
10       [--left=path] [--right=path]
11

DESCRIPTION

13       gentoo is a file manager for Linux and compatible  systems.  It  allows
14       you  to  interactively  navigate  your file system using the mouse, and
15       also to perform various fairly standard operations (such as copy, move,
16       rename, ...)  on the files and directories contained therein.
17
18       gentoo  always  shows you the contents of two directories at once. Each
19       of these is displayed in its own scrollable list, called a pane. At any
20       time,  exactly  one pane is the current pane, and has a highlighted bar
21       running across its top region. The current pane acts as the source  for
22       all  file  operations, while the other pane is the destination. You can
23       select rows in panes using  selection  methods  of  varying  complexity
24       (from  simply clicking a row, to selecting rows by name using a regular
25       expression). Once you have a selection, you can click a button to  per‐
26       form some command on the selected files.
27
28       All  file operations performed by gentoo are implemented natively. When
29       you use gentoo to copy a file, for example, gentoo does not simply exe‐
30       cute  the system's cp(1L) command. Rather, gentoo contains its own code
31       for opening source and destination files, and then reading and  writing
32       the  right  amount of data between them. This way of doing things makes
33       gentoo independent of the availability of shell commands to do things.
34
35       gentoo incorporates a fairly powerful, object-oriented file typing  and
36       styling  system.  It can use a variety of ways to determine the type of
37       the files it is displaying. Each  type  is  then  linked  to  something
38       called  a  style,  which controls how rows of that type are rendered in
39       panes. You can use this system to control icons,  colors,  and  various
40       operations  on the rows. For example, it is easy to make gentoo display
41       all PNG images in red, and to invoke The GIMP(1) on them  when  double-
42       clicked.
43
44       A design goal with gentoo has been to provide full GUI configurability,
45       removing the need to edit a configuration file by hand and restart  the
46       program to see the changes, as is otherwise common in many programs for
47       Un*x. As a result of this, gentoo features a Configuration dialog  win‐
48       dow  where  you  can  configure most aspects of its operation directly,
49       using the mouse and standard GUI widgets.
50
51       gentoo borrows its basic look'n'feel from the classic Amiga  file  man‐
52       ager Directory OPUS, but is not a "clone" of any kind.
53

OPTIONS

55       gentoo  is not primarily driven by command line arguments, but the fol‐
56       lowing are available:
57
58       --version
59              Causes gentoo to print its version number (a string on the  form
60              MAJOR.MINOR.MICRO,  like  0.11.55)  to  the standard output, and
61              then exit successfully. Numbers having an  odd  MINOR  component
62              indicate development versions of the program.
63
64       --locale-info
65              Makes  gentoo  print a couple of localization settings, and then
66              exit.  This is mostly useful during development  and  debugging,
67              and not of a lot of interest when just using the application.
68
69       --root-ok
70              Makes  gentoo  accept being run by the root user. Normally, this
71              is not allowed since it is considered a  big  threat  to  system
72              security.  Note  that  gentoo  has  the ability to execute user-
73              defined strings using the execvp(3) function. This is  generally
74              considered  harmful.  However,  if you really want to run gentoo
75              while logged on as root, supplying this option allows you to. It
76              is not recommended, though.
77
78       --no-rc
79              Starts  up  gentoo  without loading any configuration file. This
80              makes it run using the built-in defaults, which are very Spartan
81              indeed.  Seldom  comfortable, but occasionally handy when trying
82              to determine if a problem is with the configuration or with  the
83              core code.
84
85       --no-gtkrc
86              Avoids  loading the GTK+ RC file, thus disabling any widget cus‐
87              tomizations, and forces all widgets  to  use  the  default  GTK+
88              look.
89
90       --no-fam
91              Disables  use  of  FAM  (File Alteration Monitor) to detect when
92              contents of a displayed pane change. Option  only  available  if
93              gentoo was built with FAM support to begin with.
94
95       --left, --right (or -1, -2)
96              Sets the initial path for the left and right pane, respectively.
97              If present, the path specified with one of these  options  over‐
98              rides  any  other path for the pane in question. See below (Ini‐
99              tial Directory Paths) for details.
100
101       --run ARG (or -rARG)
102              Runs ARG, a gentoo command. Commands specified this way are exe‐
103              cuted before gentoo accepts any user input through the graphical
104              interface, but after the configuration file has  been  read  in.
105              You  can  use  it many times in order to make gentoo run a whole
106              series of commands. Remember that  gentoo's  command  names  are
107              case-sensitive, and that built-in commands (like "About") always
108              begin with a capital letter.
109
110
111       Any non-option command arguments will be silently ignored. If an  argu‐
112       ment  "-h" or "--help" is given, gentoo will give a summary of its sup‐
113       ported command line options and exit successfully. If an unknown option
114       is given, or a option is missing a required argument, gentoo will whine
115       and exit with a failure.
116

BASIC USAGE

118       When gentoo starts up, it will open up its single main window, which is
119       split  vertically (or horizontally; it's configurable) down the middle,
120       forming the two panes mentioned above. It also contains a bank of  but‐
121       tons along the bottom.
122
123   Initial Directory Paths
124       The actual paths shown in the two panes upon start-up can be controlled
125       in various ways. There are four ways of getting a path to  show  up  in
126       pane. In order of decreasing priority, they are:
127
128       1. Command-line Argument
129              Using  the  --left and --right (or their short forms, -1 and -2)
130              command-line arguments overrides any other setting.
131
132       2. Configured Default Directory
133              If no command-line argument is present, and the "Default  Direc‐
134              tory" configuration option is set, that directory is used.
135
136       3. Most Recently Visited Directory
137              If no default directory exists, the most recently visited direc‐
138              tory is taken from the directory history  for  each  pane.  This
139              only  works  if  a  directory  history  file  has been found and
140              loaded.
141
142       4. Current Directory
143              If all else fails, gentoo uses the current directory (".").
144
145   Navigating
146       Navigating around the file system using gentoo is very simple. The  two
147       panes  act  as independent views of the file system, and both are navi‐
148       gated in exactly the same way.
149
150       You can always see which directory a pane is  showing  by  reading  its
151       path,  shown  in  the  entry  box below (by default--you can change the
152       position to above) the pane.
153
154       To enter a directory, locate it in the pane and double  click  it  with
155       the  left  mouse button. gentoo will read the directory's contents, and
156       update the display accordingly.
157
158       There are several ways of going up in the directory structure. To enter
159       the  directory  containing  the  one currently shown (the current dir's
160       parent), you can: click the parent button (to  the  left  of  the  path
161       entry box); hit Backspace on your keyboard; click the middle mouse but‐
162       ton; select "Parent" from the pop-up menu on the right mouse button, or
163       click the downward arrow to the right of the path box (this pops up the
164       directory history menu), then select the second row from the top.
165
166   Selecting Files
167       Before you can do anything to a file, you need to select it. All  file-
168       management  commands  in  gentoo act upon the current selection (in the
169       current pane). There are several ways of selecting files, but the  most
170       frequently  used  are mouse-based. Note that the word "file" used below
171       really should be taken to mean "file  or  directory",  since  selection
172       doesn't distinguish between the two.
173
174       To select a file (or directory), just point the mouse at the name (any‐
175       where in the row is fine), and click the left mouse button. The  colors
176       of  the  clicked  row  will  change,  indicating  that  it is currently
177       selected. To select more rows, keep the mouse button down, and drag the
178       mouse  vertically.  gentoo  extends  the  selection, including all rows
179       touched.  If you drag across the top or bottom border,  the  pane  will
180       scroll,  trying to keep up.  This is a very quick and convenient way of
181       selecting multiple files, as long as they are listed in succession.
182
183       If you click again on an already selected file, you will  unselect  it.
184       You can drag to unselect several files, just as when selecting.
185
186       To select a sequence of files without dragging, first click normally on
187       the first file that you wish to select. Then release the mouse  button,
188       locate  the  last file in the sequence (it can be either above or below
189       the first one), hold down shift on your keyboard, and click the  wanted
190       file.  gentoo  now adds all files between the first and the last to the
191       current selection.
192
193       If you follow the instructions given above to select  a  sequence,  but
194       press control rather than shift before clicking the second time, gentoo
195       will unselect the range of files indicated.
196
197       If you click on a file with the meta key held down (that's  actually  a
198       key  labeled Alt, located to the immediate left of the space bar, on my
199       PC keyboard), gentoo will do something cool: it will select  (or  unse‐
200       lect,  it's a toggle just like ordinary selection) all files, including
201       the clicked one, that have the same type as the one you  clicked.  This
202       can  be  used  to select for example all PNG image files in a directory
203       even if you can only see one. Occasionally very useful.
204
205       If you click on a file with both the shift and control keys held  down,
206       gentoo will toggle the selected state of all files having the same file
207       name extension as the one you clicked. This can sometimes be useful  to
208       select  files that you don't have a proper type defined for, as long as
209       those files do share an extension, that is.
210
211   Changing Sort Order
212       The files and directories listed in each  of  gentoo's  two  panes  are
213       always  sorted  on  some  column: typically file name. You can chose to
214       sort on some other field by clicking the appropriate column title once.
215       If  you click on the field that is already current, the sorting will be
216       reversed (i.e., for names it will be Z-A rather than A-Z).
217
218       If your display includes icons, try sorting on that column: gentoo will
219       then  order  each  row  according  to its File Style, grouping the rows
220       based on their parent styles, all the way up to the root of  the  Style
221       tree.  This means that, for example, JPEG and PNG pictures (both having
222       an immediate parent style of Image) will be shown together, and  before
223       all Text files (HTML, man pages and so on). It's quite cool, really. :)
224
225   Executing Commands
226       Commands are used to make gentoo do stuff. The typical command operates
227       upon the set of selected files in the current pane, so it's  usually  a
228       good  idea  to first select some files. See the previous subsection for
229       details on how to  select  files.  Once  you  have  a  bunch  of  files
230       selected,  you  need to tell gentoo which command to execute. There are
231       several ways of doing this.
232
233       Most basic file operations (e.g. copy, move, rename,  and  so  on)  are
234       found  on  the  (cleverly labeled) buttons along the bottom of gentoo's
235       main window. To copy a file, just select  it,  then  click  the  button
236       labeled  "Copy".  It's  really  that simple. Most of these built-in (or
237       native) commands automatically operate recursively on  directories,  so
238       you  could  copy (or move) a whole directory of files by just selecting
239       it and then clicking "Copy".
240
241       If you can't see a button that does what you  want  to  do,  there's  a
242       chance  that the command exists, but isn't bound. Click the right mouse
243       button in a pane, this opens up the  "pane  pop-up  menu".  Select  the
244       "Run..." item. This opens up a dialog window showing all available com‐
245       mands. Select a command, and click "OK" to execute it.
246

CONFIGURATION

248       gentoo is a pretty complicated program; it has a rather large amount of
249       configuration  data  that  it  needs  in order to be really useful. For
250       example, my current personal configuration file contains  well  over  a
251       thousand different configuration values.
252
253       To store this hefty amount of configuration data, gentoo uses a heavily
254       structured configuration file. In fact, the file is  (or  at  least  it
255       should be) legal XML!
256
257       When new features are added to gentoo, they will typically require some
258       form of configuration data. This data is then simply added somewhere in
259       the  existing  configuration  file  structure. Effort is made to assign
260       reasonable built-in default values for all such new features, so  older
261       configuration  files (that don't contain the values required by the new
262       features) should still work. The first time you hit "Save" in the  con‐
263       figuration  window after changing your version of gentoo, your personal
264       configuration file will be updated to match the version of gentoo.
265
266       Describing how to go about configuring gentoo is too big a topic for  a
267       manual  page  to  cover.  I'll just say that the command to open up the
268       configuration window is called "Configure". It is by default  available
269       on a button (typically the top-right one), in the pane pop-up menu, and
270       also by pressing the C key on your keyboard.
271

FILES

273       ~/.gentoorc
274              A user's personal configuration file. When gentoo starts up,  it
275              will  try  to load this file. If the file isn't found, the site-
276              wide configuration will be tried instead.
277
278       /usr/local/etc/gentoorc
279              This is the site-wide configuration file. If a user doesn't have
280              a  configuration  in  his/her  home directory, gentoo loads this
281              file instead. The actual location of this file is slightly  sys‐
282              tem-dependent,  the  above  is  the default. As an end user, you
283              typically won't need to access this file manually.
284
285       ~/.gentoo-history
286              This file contains lists of the most recently  visited  directo‐
287              ries,  for  both  panes.  These are the lists that appear in the
288              drop-down menu when the arrow next to  the  path  entry  box  is
289              clicked. Can be disabled in the Dir Pane configuration.
290
291       ~/.gentoogtkrc
292              This  file allows you to control the look of the widgets used by
293              gentoo, through the GTK+ style system. This file must be present
294              in  the  user's home directory - there is no site-wide GTK+ con‐
295              figuration file.
296
297       /etc/passwd, /etc/group
298              These two files normally hold the system's  password  and  group
299              information.   These  are (probably) the ones gentoo uses to map
300              user IDs to login names, to do tilde-expansion (mapping of  user
301              name  to  directory  path), and to map group IDs to group names.
302              That is probably, because gentoo doesn't actually refer to these
303              files  by  name.  Instead,  it uses the (BSD-style) API function
304              calls getpwent(3) and getgrent(3) to access this information.
305
306       /etc/fstab, /proc/mounts, (or /etc/mtab)
307              These files contain data on available and mounted file  systems.
308              They  are read by gentoo's auto-mounting code. You can configure
309              the exact file names used, on the "Mounting"  tab  in  the  main
310              configuration  window.  Note that using /proc/mounts rather than
311              /etc/mtab is recommended on Linux systems; they contain  roughly
312              the  same  data,  but the one in /proc is always up to date, and
313              faster to read!
314
315

BUGS

317       All releases of gentoo numbered 0.x.y, where x  (the  so  called  minor
318       version  number)  is odd, are to be considered development releases, as
319       opposed to stable ones. This means that the software will probably suf‐
320       fer  from bugs. If you find something that you suspect is indeed a bug,
321       please don't hesitate to contact the author!  For details on how to  do
322       this, see below.
323
324       If you're concerned about using potentially buggy and completely unwar‐
325       ranted software to manage your precious files, please feel free not  to
326       use gentoo. The world is full of alternatives.
327
328       The  chances  that  a bug gets fixed increase greatly if you report it.
329       When reporting a bug, you must describe how to reproduce it,  and  also
330       try  to  be  as detailed and precise as possible in your description of
331       the actual bug. If possible, perhaps you should include the  output  of
332       gdb(1) (or whatever your system's debugger is called). In some cases it
333       might be helpful if you include the configuration file you  were  using
334       when  the  problem  occurred.  Before reporting a bug, please make sure
335       that you are running a reasonably recent version of the software, since
336       otherwise  "your"  bug  might  already been fixed. See below for how to
337       obtain new releases.
338
339       Also, you should locate and read through the BUGS file distributed with
340       gentoo,  so  you  don't  go  through  all this hassle just to report an
341       already known bug, thereby wasting everybody's time...
342

AUTHOR

344       gentoo was written, from scratch, by Emil Brink. The first line of code
345       was  written  on May 15th, 1998. It is my first program to use the GTK+
346       GUI toolkit, my first program to be released under the GPL, and also my
347       first  really major Linux application. However, it is not my first pro‐
348       gram! ;^) I've been writing (increasingly complex) code for almost  two
349       decades  now.  I  have recently finished my Master of Science degree in
350       Computer Science and Engineering at the Royal Institute  of  Technology
351       in Stockholm, Sweden.
352
353       The only efficient way to contact me (to report bugs, give praise, sug‐
354       gest features/fixes/extensions/whatever)  is  by  Internet  e-mail.  My
355       address  is <emil@obsession.se>.  Please try and include the word "gen‐
356       too" in the Subject part of your e-mail, to help me organize my  inbox.
357       Thanks.
358

ACKNOWLEDGMENTS

360       The  author wishes to thank the following people for their various con‐
361       tributions to gentoo:
362
363       Johan Hanson (<johan@tiq.com>)
364              Johan is the man behind all icon graphics in  gentoo,  and  also
365              the  author  of  the custom widgets used in it. He also comes up
366              with plenty of ideas for new features and changes to  old  ones,
367              some   of  which  are  even  implemented.  Johan  has  stuff  at
368              <http://www.bahnhof.se/~misagon/>.
369
370       Jonas Minnberg (<sasq@nightmode.org>)
371              Jonas did intensive testing of early  versions  of  gentoo,  and
372              eventually  persuaded  me into releasing it (back around version
373              0.9.7 or so).
374
375       Ulf Petterson (<ulf@obsession.se>)
376              Ulf drew the main gentoo logo (the one shown in the  About  win‐
377              dow), and also designed the main HTML documentation's layout.
378
379       Josip Rodin (<jrodin@jagor.srce.hr>)
380              Maintainer  of  the  gentoo package for Debian Linux, and also a
381              source of suggestions for improvements, as well as a  relay  for
382              bug reports from Debian Linux users.
383
384       Ryan Weaver (<ryanw@infohwy.com>)
385              Maintainer  of the gentoo packages for Red Hat Linux, and proba‐
386              bly one of the fastest package creators out there. :)
387
388       Oliver Braun, Jim Geovedi and Pehr Johansson
389              Maintainers of gentoo ports to  FreeBSD,  OpenBSD,  and  NetBSD,
390              respectively.
391
392       Thanks  also  to  all people who have mailed me about gentoo, providing
393       bug reports, feature requests, and the occasional kind word.  :^)  It's
394       because  of people like yourselves that we have this wonderful computer
395       platform to play with.
396
398       gentoo is released as free, open-source software, under  the  terms  of
399       the  GNU  General  Public License (GNU GPL), version 2. This license is
400       included in the distribution under the traditional name of COPYING, and
401       I suggest that you read it if you're not familiar with it. If you can't
402       find the file, but have Internet access,  you  could  take  a  look  at
403       <http://www.gnu.org/>.   It  is important to realize that the mentioned
404       license means that there is ABSOLUTELY NO WARRANTY for this software.
405

OTHER INFO

407       Some unfinished, outdated, but still pretty  informative  documentation
408       is  available, in HTML format, in the docs/ subdirectory in the distri‐
409       bution archive. If you  haven't  installed  gentoo  from  the  original
410       .tar.gz distribution archive, you might need to either inspect the dis‐
411       tribution you did use (perhaps it came as some form of  "package"),  or
412       contact a system administrator.
413
414       The   GTK+   GUI   toolkit   that   gentoo  requires  is  available  at
415       <http://www.gtk.org/>.   gentoo  uses  the  slightly  outdated   stable
416       series,  called  1.2.x. The latest known release in that series is GTK+
417       1.2.10. Because of severe performance problems,  gentoo  will  probably
418       not be ported to use the current (2.0.x) series of GTK+ any time soon.
419
420       The latest version of gentoo is always available on the official gentoo
421       home page, at <http://www.obsession.se/gentoo/>.
422

SEE ALSO

424       regex(7), file(1), magic(5), fstab(5), strftime(3)
425
426       Manual page section numbers in this page refer to sections  on  (some?)
427       Linux  systems,  your mileage will most likely vary. Try the apropos(1)
428       command, it might help you out.
429
430
431
432Obsession Development            August, 2006                       gentoo(1x)
Impressum