Merge pull request #701 from trapexit/faq

add faq entry on files ending up on 1 branch

README.md

@@ -1,6 +1,6 @@
 % mergerfs(1) mergerfs user manual
 % Antonio SJ Musumeci <trapexit@spawn.link>
-% 2020-01-19
+% 2020-01-24
 
 # NAME
 
@@ -934,6 +934,15 @@ That said, for the average person, the following should be fine:
 `-o use_ino,cache.files=off,dropcacheonclose=true,allow_other,category.create=mfs`
 
 
+#### Why are all my files ending up on 1 drive?!
+
+Did you start with empty drives? Did you explicitly configure a `category.create` policy?
+
+The default create policy is `epmfs`. That is a path preserving algorithm. With such a policy for `mkdir` and `create` with a set of empty drives it will naturally select only 1 drive when the first directory is created. Anything, files or directories, created in that first directory will be placed on the same branch because it is preserving paths.
+
+This catches a lot of new users off guard but changing the default would break the setup for many existing users. If you do not care about path preservation and wish your files to be spread across all your drives change to `mfs` or similar policy as described above.
+
+
 #### Do hard links work?
 
 Yes. You need to use `use_ino` to support proper reporting of inodes.

man/mergerfs.1

@@ -1,7 +1,7 @@
 .\"t
 .\" Automatically generated by Pandoc 1.19.2.4
 .\"
-.TH "mergerfs" "1" "2020\-01\-19" "mergerfs user manual" ""
+.TH "mergerfs" "1" "2020\-01\-24" "mergerfs user manual" ""
 .hy
 .SH NAME
 .PP
@@ -1963,6 +1963,24 @@ the documentation will be improved.
 That said, for the average person, the following should be fine:
 .PP
 \f[C]\-o\ use_ino,cache.files=off,dropcacheonclose=true,allow_other,category.create=mfs\f[]
+.SS Why are all my files ending up on 1 drive?!
+.PP
+Did you start with empty drives?
+Did you explicitly configure a \f[C]category.create\f[] policy?
+.PP
+The default create policy is \f[C]epmfs\f[].
+That is a path preserving algorithm.
+With such a policy for \f[C]mkdir\f[] and \f[C]create\f[] with a set of
+empty drives it will naturally select only 1 drive when the first
+directory is created.
+Anything, files or directories, created in that first directory will be
+placed on the same branch because it is preserving paths.
+.PP
+This catches a lot of new users off guard but changing the default would
+break the setup for many existing users.
+If you do not care about path preservation and wish your files to be
+spread across all your drives change to \f[C]mfs\f[] or similar policy
+as described above.
 .SS Do hard links work?
 .PP
 Yes.