The Linux filesystem hierarchy (FHS) contains a lot of important directories. For example, I just discovered /sys/class/input while playing with my PS/2 keyboard settings.

But all those important directories are documented elsewhere, so man /sys/class/input doesn't work to explain what happens at a certain point.

Why not place README files into the hierarchy to make it easier for people to learn what's going on at certain levels and play with the contents? It would be really awesome if devices could even mount their own READMEs.

  • 2
    Perhaps because most people don't want to learn what is going on at those different levels? They just want them to work, so they can accomplish whatever tasks they need/want to do. Someone would have to write all those README files, and they'd add more bloat to a file system already overloaded with things (like much of /usr/share) that most people will never use.
    – jamesqf
    Jan 7, 2018 at 18:38
  • 14
    @jamesqf because most people don't want to learn what is going on at those different levels? They just want them to work, so they can accomplish whatever tasks they need/want to do And what if my task is related to the file system, like the OP's seems to be? Also, have you met a Linux user? We do want to learn. This is a terrible argument.
    – kaqqao
    Jan 8, 2018 at 0:23
  • 1
    The fundamental difference between Linux and Windows/Mac, in case you have not noticed, is that Linux knows that you left the womb already knowing everything. Hence a README would be redundant.
    – user541686
    Jan 8, 2018 at 0:34
  • 1
    @kaqqao: Well, I AM a Linux user, and have been one pretty much since there WAS a Linux. And before that a user of Unix since it ran on my school's PDP-11. I don't particularly care how things like the file system work, I just (at the moment) want to get my seismic tomography code working. Nor do I care about /sys/class/input, as long as my keyboard & trackball work. For the small minority who are interested in these things, there is a handy tool called Google, accessible from most web browsers :-)
    – jamesqf
    Jan 8, 2018 at 5:02
  • 2
    There's man hier. Jan 8, 2018 at 6:19

2 Answers 2


To use your example: /sys/ doesn't contain "real" files, but is entirely provided by the kernel. Do you want all READMEs to become part of the kernel? You probably don't.

Documentation is in /usr/share/doc. Which contains normal files on your harddisk. Some documentation about /sys and /proc is in the kernel source, that is in /usr/src/linux/Documentation (if you've installed the kernel source, and made the symlink for your current kernel).

  • 10
    sysfs and procfs are fully virtual filesystems that have no backing store. Everything in there is synthesized on the fly by the kernel. If the READMEs are not stored in memory, where else would they come from? Jan 7, 2018 at 13:39
  • 13
    @JörgWMittag: Obviously the kernel could synthesise symlinks to /use/share/doc.
    – MSalters
    Jan 7, 2018 at 14:02
  • 11
    The kernel is already a large and complicated piece of software, and "making it easier for people to learn" is not among the main goals of their developers. It's not that hard to go to /usr/share/doc instead. Jan 7, 2018 at 15:24
  • 9
    @MSalters: that would mean that the kernel has to either a) scan the entire filesystem to find those files and create symlinks to them, b) has to have a load of configuration options to tell the kernel where those files are so that it can create symlinks to them, or c) has to prescribe the locations of those files to the distribution maintainers (which would violate Linus's #1 maxim that policy belongs in userspace, only mechanism belongs in the kernel). Also, how do you make sure that the files match up with the currently running kernel version? What about distributions which have their … Jan 7, 2018 at 17:57
  • 7
    @FedericoPoloni: the FHS is only mandatory for Linux distributions conforming to the LSB. Most don't. In particular, there are a number of distributions which were specifically founded to clean up (what they perceive as) historical cruft, which in many cases explicitly includes the FHS. Jan 7, 2018 at 20:53

Because Unix and Linux have a decades old tradition of documenting with man pages (and, on GNU systems, info files ...). See man(1), man(7), man-pages(7). BTW, man command and pages are optional (and you won't install them on every Unix system).

The file system hierarchy is described in hier(7).

It is defined by the Filesystem Hierachy Standard available on https://wiki.linuxfoundation.org/lsb/fhs

Several filesystems, notably /proc/ (see proc(5)) and /sys/ (see sysfs(5)) are pseudofile systems provided by the kernel code. You don't want to bloat the kernel with extra code producing such README-s (which is useless to the vast majority of users). Even the kernel's configuration file is only optionally available as /proc/config.gz which is often disabled in most kernel configurations. And many Linux systems are embedded systems (e.g. your smartphone, your smart appliance or IoT device, your RaspberryPI) where resources are scare enough to avoid being wasted.

Notably /sys/ is mostly useful to sysadmins and to developers writing low-level utilities, and both are supposed to be able to find documentation appropriately.

Why not to place README files into the hierarchy to make it easier for people to learn what's going on

If you really want such READMEs, write your own loadable kernel module providing them, or setup some unionfs to provide them. I don't think it is worth the effort (and a unionfs on /sys would probably slow down your entire system).

Remember that kernel code consumes RAM (it is never paged out and sits in physical memory, not virtual memory), even if not used. So it makes sense to avoid bloating it.

  • So I can write a package that documents all those paths without touching kernel or making it bloat? Jan 8, 2018 at 14:23
  • 1
    You could, but using a unionfs on /sys would slow down your system. I don't think it is worth losing your time in such way. Life is short... And you'll spend more time doing that than reading the documentation Jan 8, 2018 at 14:25

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .