Sort entries in Format 1 files by path, ASCIIbetically.

This ensures that the files are stable, and not subject to the order in
which the OS returns directory entries. This should prevent unnecessary
changes, and therefore unnecessary merge conflicts.

1 files changed, 16 insertions, 0 deletions

diff --git a/FILEFORMAT_1 b/FILEFORMAT_1
index b16d85a..189cc84 100644
--- a/FILEFORMAT_1
+++ b/FILEFORMAT_1
@@ -86,3 +86,19 @@ such as RTL/LTR marks (U+200E/U+200F) to prevent the possibility of "Trojan
 Source" type attacks.
 
 (See <https://lwn.net/Articles/874951/> for more info on "Trojan Source")
+
+
+### Sorting
+
+To generate stable metatdata files that do not depend on the order that files
+are returned by `readdir()`, which would producing spurious diffs, sort entries
+by path ASCIIbetically, as with `strcmp(3)`. But we don't require metadata files
+to be sorted when reading them.
+
+If we read two entries for the same path, the results are currently unspecified.
+
+Users should probably avoid sorting Format 1 files with standard tools like
+`sort(1)`, as the HEADER line must always be first, and also URL-encoded
+characters will throw off the sort order. Also, tools like `sort` will typically
+sort according to the current locale, e.g. using `strcoll(3)` rather than
+`strcmp()`.