README.rst
1dirsync
2=======
3
4|copyright| 2014-2019 Thomas Khyn
5|copyright| 2003-2015 Anand B Pillai
6
7Advanced directory tree synchronisation tool
8
9based on `Python robocopier`_ by Anand B Pillai
10
11If you like dirsync and are looking for a way to thank me and/or encourage
12future development, here is my BTC or BCH donation address:
13``1EwENyR8RV6tMc1hsLTkPURtn5wJgaBfG9``.
14
15Usage
16-----
17
18From the command line::
19
20 dirsync <sourcedir> <targetdir> [options]
21
22From python::
23
24 from dirsync import sync
25 sync(sourcedir, targetdir, action, **options)
26
27
28Main Options
29------------
30
31Chosing one option among the following ones is mandatory
32
33--diff, -d Only report difference between sourcedir and targetdir
34--sync, -s Synchronize content between sourcedir and targetdir
35--update, -u Update existing content between sourcedir and targetdir
36
37If you use one of the above options (e.g. ``sync``) most of the time, you
38may consider defining the ``action`` option in a `Configuration file`_ parsed
39by dirsync.
40
41
42Additional Options
43------------------
44
45--verbose, -v Provide verbose output
46--purge, -p Purge files when synchronizing (does not purge by
47 default)
48--force, -f Force copying of files, by trying to change file
49 permissions
50--twoway, -2 Update files in source directory from target
51 directory (only updates target from source by default)
52--create, -c Create target directory if it does not exist (By
53 default, target directory should exist.)
54--ctime Also takes into account the source file\'s creation
55 time (Windows) or the source file\'s last metadata
56 change (Unix)
57--content Takes into account ONLY content of files.
58 Synchronize ONLY different files.
59 At two-way synchronization source files content
60 have priority if destination and source are existed
61--ignore, -x patterns Regex patterns to ignore
62--only, -o patterns Regex patterns to include (exclude every other)
63--exclude, -e patterns Regex patterns to exclude
64--include, -i patterns Regex patterns to include (with precedence over
65 excludes)
66
67
68Configuration file
69------------------
70
71.. note::
72 Configuration files are only used when using the command line, and ignored
73 when dirsync is called from within Python.
74
75If you want to use predefined options all the time, or if you need specific
76options when 'dirsyncing' a specific source directory, dirsync looks for
77two configuration files, by order or priority (the last takes precedence)::
78
79 ~/.dirsync
80 source/directory/.dirsync
81
82.. note::
83 A ~/.dirsync configuration file is automatically created the first time
84 dirsync is ran from the command line. It enables ``sync`` mode by default.
85
86.. warning::
87 Any ``source/directory/.dirsync`` file is automatically excluded from the
88 files to compare. You have to explicitly include using the ``--include``
89 option it if you want it to be covered by the comparison.
90
91The command line options always override the values defined in the
92configuration files.
93
94The configuration files must have a ``defaults`` section, and the options are
95as defined above. The only exception is for the option ``action``, which can
96take 3 values ``diff``, ``sync`` or ``update``.
97
98Example config file::
99
100 [defaults]
101 action = sync
102 create = True
103
104
105Custom logger
106-------------
107
108From python, you may not want to have the output sent to ``stdout``. To do so,
109you can simply pass your custom logger via the ``logger`` keyword argument of
110the ``sync`` function::
111
112 sync(sourcedir, targetdir, action, logger=my_logger, **options)
113
114
115.. |copyright| unicode:: 0xA9
116
117.. _`Python robocopier`: http://code.activestate.com/recipes/231501-python-robocopier-advanced-directory-synchronizati/
118