56beec94e99a44c33ef68a54f9e3b1461720471b
[sgodup.git] / README
1                   sgodup -- file deduplication utility
2                   ====================================
3
4 sgodup is utility for files deduplication. You supply two directories:
5 the base and one with possible duplicates, utility determines duplicate
6 files and replaces them with the links. It is aimed to have very high
7 performance.
8
9 SINGLE PASS MODE
10 ================
11
12 $ sgodup -basedir DIR -dupdir DIR -action ACTION \
13   [-minsize NNN] [-chmod NNN] [-fsync]
14
15 basedir is a directory with "original" files, that are possible link
16 targets. dupdir is a directory with possible duplicates, which are to be
17 replaced with the links to basedir's file. It is safe to specify same
18 directory as a basedir and dupdir.
19
20 There are 3 stages this command will do:
21
22 * basedir directory scan: collect all *regular* file paths, sizes and
23   inodes. If -chmod is specified, then apply it to them. Files smaller
24   than -minsize (by default it is equal to 1 bytes) are not taken for
25   duplication comparison
26 * dupdir directory scan: same as above. If there is no basedir's file
27   with the same size, then skip dupdir's one (obviously it can not be
28   duplicate). Check that no basedir's files have the same inode, skip
29   dupdir's file otherwise (it is hardlink)
30 * deduplication stage. For each dupdir file, find basedir one with the
31   same size and compare their contents, to determine if dupdir one is
32   the duplicate. Perform specified action if so. Comparing is done the
33   following way:
34   * read first 4 KiB (one disk sector) of each file
35   * if that sector differs, then files are not duplicates
36   * read each file's contents sequentially with 128 KiB chunks and
37     calculate BLAKE2b-512 digest
38
39 Action can be the following:
40
41 * print: print to stdout duplicate file path with corresponding relative
42   path to basedir's file
43 * symlink: create symbolic link with relative path to corresponding
44   basedir's file
45 * hardlink: create hard link instead
46 * ns: write to stdout series of netstring encoded pairs of duplicate
47   file path and its corresponding basedir's one. It is used in two pass
48   mode. Hint: it is highly compressible
49
50 If -fsync is specified, then fsync directories where linking occurs.
51
52 Progress is showed at each stage: how many files are counted/processed,
53 total size of the files, how much space is deduplicated.
54
55     2020/03/19 22:57:07 processing basedir...
56     2020/03/19 22:57:07 464,329 / 0 (0%) files scanned
57     2020/03/19 22:57:07 534 GiB / 0 B (0%)
58     2020/03/19 22:57:12 processing dupdir...
59     2020/03/19 22:57:12 362,245 / 0 (0%) files scanned
60     2020/03/19 22:57:12 362 GiB / 0 B (0%)
61     2020/03/19 22:57:17 deduplicating...
62     2020/03/19 22:58:18 8,193 / 362,245 (2%) files processed
63     2020/03/19 22:58:18 7.7 GiB / 362 GiB (2%) deduplicated
64     [...]
65     2020/03/20 11:17:20 321,123 files deduplicated
66
67 TWO PASS MODE
68 =============
69
70 $ sgodup -basedir DIR -dupdir DIR -action ns [-minsize NNN] [-chmod NNN] > state
71 $ sgodup -action ACTION [-fsync] -ns < state
72
73 If you are dealing with huge amount of small files, then simultaneous
74 reading (duplicate detection) and writing (duplicate files linking) on
75 the same disk can dramatically decrease performance. It is advisable to
76 separate the whole process on two stages: read-only duplicates
77 detection, write-only duplicates linking.
78
79 Start sgodup with "-action ns" and redirect stdout output to some
80 temporary state file, for storing detected duplicate files information
81 in it. Then start again with "-ns state" option to relink files.
82
83 SAFETY AND CONSISTENCY
84 ======================
85
86 It was not tested on 32-bit platforms and probably won't work on them
87 correctly.
88
89 POSIX has no ability to atomically replace regular file with with
90 symbolic/hard link. So file is removed first, then link created. sgodup
91 cautiously prevents possible interruption by signal (TERM, INT) of those
92 two calls. But any other failure could possibly break the program after
93 file removal without link creation, leading to its loss!
94
95 It is recommended to use filesystems with snapshot capability to be able
96 to rollback and restore removed file. Or you can use "-action print"
97 beforehand to collect the duplicates and use it as a log for possible
98 recovery.
99
100 There are no warranties and any defined behaviour if directories (and files
101 within) where utility is working with are modified.
102
103 LICENCE
104 =======
105
106 This program is free software: you can redistribute it and/or modify
107 it under the terms of the GNU General Public License as published by
108 the Free Software Foundation, version 3 of the License.
109
110 This program is distributed in the hope that it will be useful,
111 but WITHOUT ANY WARRANTY; without even the implied warranty of
112 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
113 GNU General Public License for more details.