README

   1 glocate -- ZFS-diff-friendly locate-like utility
   2
   3 This utility is intended to keep the database of filesystem hierarchy
   4 and quickly display some part of it. Like ordinary *locate utilities.
   5 But unlike others, it is able to eat zfs-diff's output and apply the
   6 changes to existing database.
   7
   8 Why I wrote it? Indexing, just "find /big" can take a considerable
   9 amount of time, like an hour or so, with many I/O operations spent. But
  10 my home NAS has relatively few number of changes made every day. The
  11 only possible quick way to determine what exactly was modified is to
  12 traverse over ZFS'es Merkle trees to find a difference between
  13 snapshots. Fortunately zfs-diff command does exactly that, providing
  14 pretty machine-friendly output.
  15
  16 Why this utility is so complicated? Initially it kept all database in
  17 memory, but that takes 2-3 GiBs of memory, that is huge amount. Moreover
  18 it fully loads it to perform any basic searches. So current
  19 implementation uses temporary files and heavy use of data streaming.
  20
  21 Its storage format is simple: Zstandard-compressed list of records:
  22
  23 * 16-bit BE size of the following name
  24 * entity (file, directory, symbolic link, etc) name itself.
  25   Directory has trailing "/"
  26 * single byte indicating current file's depth
  27 * 64-bit BE mtime seconds
  28 * 64-bit BE file or directory (sum of all files and directories) size
  29
  30 Its indexing algorithm is following:
  31
  32 * traverse over all filesystem hierarchy in a *sorted* order. All
  33   records are written to temporary file, without directory sizes,
  34   because they are not known in advance during the walking
  35 * during the walk, remember in memory each directory's total size
  36 * read all records from that temporary file, writing to another one, but
  37   replacing directory sizes with ones remembered
  38
  39 Searching is trivial:
  40
  41 * searching is performed on each record streamed from the database
  42 * if -root is specified, then search will stop after that hierarchy part
  43   is over
  44 * by default all elements are printed, unless you provide a single
  45   argument that becomes "*X*" pattern matched on case-lowered path
  46   elements
  47
  48 Updating algorithm is following:
  49
  50 * read all [-+MR] actions from zfs-diff, validating the whole format
  51 * each file's "R" becomes "-" and "+" actions
  52 * if there are directory "R", then collect them and stream from current
  53   database to determine each path entity you have to "-" and "+"
  54 * each "+" adds an entry to the list of "M"s
  55 * sort all "-", "+" and "M" filenames in ascending order
  56 * get entity's information for each "M" (remembering its size and mtime)
  57 * stream current database records, writing them to temporary file
  58 * if record exists in "-"-list, then skip it
  59 * if any "+" exists in the *sorted* list, that has precedence over the
  60   record from database, then insert it into the stream, taking size and
  61   mtime information from "M"-list
  62 * if any "M" exists for the read record, then use it to alter it
  63 * all that time, directory size calculating algorithm also works, the
  64   same one used during indexing
  65 * create another temporary file to copy the records with actualized
  66   directory sizes
  67
  68 How to use it?
  69
  70     $ zfs snap big@snap1
  71     $ cd /big ; glocate -db /tmp/glocate.db -index
  72
  73     $ glocate -db /tmp/glocate.db
  74     [list of all files]
  75
  76     $ glocate -db /tmp/glocate.db -machine
  77     [machine parseable list of files with sizes and mtimes]
  78
  79     $ glocate -db /tmp/glocate.db -tree
  80     [beauty tree-like list of files with sizes and mtimes]
  81
  82     $ glocate -db /tmp/glocate.db -root music
  83     [just a music hierarchy path]
  84
  85     $ glocate -db /tmp/glocate.db -root music blasphemy | grep "/$"
  86     music/Blasphemy-2001-Gods_Of_War_+_Blood_Upon_The_Altar/
  87     music/Cryptopsy-1994-Blasphemy_Made_Flesh/
  88     music/Infernal_Blasphemy-2005-Unleashed/
  89     music/Ravenous-Assembled_In_Blasphemy/
  90     music/Sect_Of_Execration-2002-Baptized_Through_Blasphemy/
  91     music/Spectral_Blasphemy-2012-Blasphmemial_Catastrophic/
  92
  93 and update it carefully, providing the strip prefix to -update:
  94
  95     $ zfs snap big@snap2
  96     $ zfs diff -FH big@snap2 | glocate -db /tmp/glocate.db -update /big/
  97
  98 glocate is copylefted free software: see the file COPYING for copying
  99 conditions.