.TH DIVERGEFS 4
.SH NAME
divergefs - diverge file system
.SH SYNOPSIS
.B divergefs
[
.B -p
.I defaultpath
] [
.B -f
.I rulefile
] [
.B -h
.I holefile
] [
.B -d
.I debuglevel
] 
.I mountpoint

.SH DESCRIPTION

.I Divergefs
is a user level file server which layers arbitrary number of directory trees on
top of the base directory 
.I mountpoint 
based on user specified rules from
.I rulefile\c
\&.
Its uses include, but are not limited to, temporarily modifying a few files on
read-only media or speeding up compilation by storing object files locally
instead of on a distant file server.

.SH OPTIONS
.IP -p
Specifies a default path where the 
.I holefile
will be
.I defaultpath\c
/holes.
If 
.I rulefile 
is not specified, a default rule file will be written to
.I defaultpath\c
/rules
with content of:

.I defaultpath\c
/files   all<>

which means that 
.I defaultpath\c
/files will be layered on top of 
.I mountpoint\c
\&.
.I defaultpath
and 
.I defaultpath\c
/files will be automatically created if they do not
exist. (default
.BR /tmp 
if both 
.I rulefile
and 
.I holefile
are not specified).
.IP -f
Sets the user configuration file which defines what and how the
directory trees will be layered.
.IP -h
Specifies the file to store file or directory names that were
removed during the mounted session.  If 
.I holefile
exists, it will be used to
initialize the file system, and any file matching the filenames after mount will
be masked out. (default
.BR /tmp/holes 
or 
.I defaultpath\c
/holes 
if using default path invocation).
.IP -d 
Allows the user to specify the amount of debugging messages to be
outputted ranging from 1-5.  (default 3)

Note: any relative paths supplied either through command line arguments or
inside the rule file will be relative to the current directory when divergefs is
invoked.

.SH EXAMPLES
The easiest way to use divergefs is to call it without any argument which is
equivalent to calling it with
.B -p
.BR /tmp\c
\&.
The following is an example for building kernel:
.IP
.EX
 % divergefs /sys/src
 % cd /sys/src/9/pc
 % mk 'CONF=pccpuf'
.EE
.LP
If divergefs is invoked with default path, it will automatically output a rule
file to 
.I defaultpath\c
/rules, in this case
.BR /tmp/rules\c
, which can be modified later to suit different needs.

Default path is easy to use but is limited to layering only one directory on top
of the 
.I mountpoint 
if the supplied default rule file is used.  For more advanced
usage, writing your own config file may be necessary.  The following is an
example avoiding write-back to remote server to speed up the compilation:
.IP
.EX
 % ramfs -m /n/junk
 % cat > divergefs.conf << EOF
 /n/junk ext<8>
 /tmp/pcbuild all<>
 EOF
 % divergefs -f divergefs.conf /sys/src
 % cd /sys/src/9/pc
 % mk 'CONF=pccpuf'
.EE
.LP
After mounting, writing to
.BR /sys/src/*/*.8
will be redirected to 
.BR /n/junk/*/*.8 
while writing to other files  will be redirected to 
.BR /tmp/pcbuild/*\c
\&.

Note: the first rule 
.B ext<8> 
will be on the top of the layered directory tree
while the last rule 
.B all<> 
will be on the bottom just above the 
.I mountpoint\c
\&.

.SH HOLES
A hole is the name of a file or directory that has been removed, and thus should
not appear during any file operations.  However, if a file or directory with the
same name is created where a hole is, the hole will be filled up and replaced by
the file or directory instead.

Therefore, a more robust approach is to supply the
.I holefile
argument while mounting which defaults to 
.BR /tmp/holes\c
\&.  Hole file is necessary for the file
system to keep track of which files were removed and should not be used.  In the
case of read-only media, the files will not be actually removed, but the file
system has to simulate the effect of removing by "covering up" the filenames
through the use of a hole file.

It is suggested that you supply the
.I holefile
argument if you are not using the default path invocation, so that
.I holefile
can be reused from a previous session to recover the state on that 
.I mountpoint\c
\&.
If no
.I holefile
is specified, and there are two running instances of divergefs, then they will 
be racing for the hole file at
.BR /tmp/holes
and the result is undefined.
Therefore, it is important that you make sure the hole file from an entirely
different session is not reused.

In the case of default path invocation, if no
.I holefile
is specified, it defaults to 
.I defaultpath\c
/holes.  
If such file exists, it will be picked up to resume a previous session, so it is
ok not to specify a hole file when supplying the
.B -p
.I defaultpath
argument.


.SH SYNTAX 
config_file = (rule '\\n')*

rule = path complex_rule

path = absolute_path | relative_path

complex_rule = simple_rule (("||" | "&&") complex_rule)?

simple_rule = concrete_rule '<' setting '>' | '(' complex_rule ')'

Concrete rules and corresponding setting syntax are described in the next
section. Note: relative_path is relative to the current path at the time of
invocation.

.SH RULES
Rules are applied in the order as they appear in the config file, so that means
rules on the top will take precedence over the ones below.
.IP
.IP all<>
Matches anything. Note: the setting field must be empty.
.IP mode<setting>
setting = 'A' | 'L' | 'f' | 'd' | 'r' | 'w' | 'x' | 'e'
Matches file with the given mode.  Each mode can only have one character in
the setting field.  Please refer to test(1) for details on the meaning of each
character.  To apply multiple modes in a single rule, please use the || or &&
construct.  Example: mode<r> || mode<w>
.IP ext<setting>
setting = file extension
.IP fregex<setting>
setting = regular expression, refer to regexp(2) for details.
matches any file name that satisfies the regular expression given.
.IP dregex<setting>
setting = regular expression, refer to regexp(2) for details.
matches any directory name that satisfies the regular expression given.
.IP regex<setting>
setting = regular expression, refer to regexp(2) for details.
matches any name that satisfies the regular expression given.

.SH SOURCE
.SH SEE ALSO
Plan 9 wiki divergefs entry, http://www.cs.bell-labs.com/wiki/plan9/divergefs/

.SH BUGS
Renaming read-only directory will result in error.

The rule syntax is experimental (contact author with suggestions).