[disorderfs] 01/02: disorderfs.1.txt: Add a reproducible builds example, highlighting the non-intuitive recommendation to sort instead of shuffle.

[Chris Lamb]

This is an automated email from the git hooks/post-receive script.

lamby pushed a commit to branch master
in repository disorderfs.

commit e0f29447d05c2d47356099a5e01b57062aed021f
Author: Chris Lamb <lamby at debian.org>
Date:   Wed Nov 1 21:57:21 2017 +0100

    disorderfs.1.txt: Add a reproducible builds example, highlighting the non-intuitive recommendation to sort instead of shuffle.
---
 disorderfs.1.txt | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/disorderfs.1.txt b/disorderfs.1.txt
index dfe5cb2..2160f94 100644
--- a/disorderfs.1.txt
+++ b/disorderfs.1.txt
@@ -83,6 +83,34 @@ BUGS
 file is locked when it really isn't.
 
 
+EXAMPLE
+-------
+
+If you are attempting to test a https://reproducible-builds.org[Reproducible
+Builds] issue, it is recommended you use *--sort-dirents=yes* instead of
+*--shuffle-dirents=yes* to ensure that any difference between builds is
+deterministic in itself. For example:
+
+[source,sh]
+----
+
+$ mkdir rootdir sorted reversed
+$ touch rootdir/a rootdir/b rootdir/c <1>
+
+$ disorderfs --sort-dirents=yes --reverse-dirents=no rootdir sorted <2>
+$ ls -f sorted
+.  ..  a  b  c <3>
+
+$ disorderfs --sort-dirents=yes --reverse-dirents=yes rootdir reversed <4>
+$ ls -f reversed
+c  b  a  ..  . <5>
+----
+<1> First, we create some example files
+<2> Mount *rootdir* in sorted mode...
+<3> ... and the results are in sorted order.
+<4> We mount *rootdir* again, sorting the results in reversed order...
+<3> ... and the directory contents are returned in reverse.
+
 AUTHOR
 ------
 Andrew Ayer <agwa at andrewayer.name>

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/reproducible/disorderfs.git