-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
256 lines (176 loc) · 9.07 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
"rsyncit" notes Revised: 120710
----------------------------------------------------------------------
1. Overview.
1.1. Purpose of project.
"rsync" is a widely-used CLI (Command Level Interface) backup tool
that supports backups both to directories mounted locally and across a
network using a protocol of the same name.
This project provides a CLI wrapper for "rsync" that focuses on
local backups. The wrapper may be convenient in some cases for the
following reasons: it has a simpler interface than "rsync", it adds
sanity checks, and it handles target-directory paths consistently
(this is discussed below).
For more information on "rsync", visit:
http:https://en.wikipedia.org/wiki/Rsync
1.2. Some details.
The wrapper consists of a single Perl5 script named "rsyncit" (or
"rsyncit.pl").
"rsyncit" takes two arguments, not counting option switches: a source
directory and a target directory. The script uses "rsync" to back-up
the directory and its subdirectories to a subdirectory of the target
directory.
The target subdirectory is transformed into a mirror of the source
directory. As a consequence of this, files already stored in the sub-
directory will be deleted unless corresponding files exist in the
source directory.
The target subdirectory has the same name as the source directory,
minus any higher-level directory components. For example, the follow-
ing command transforms the directory tree "/backup/bar" into a mirror
of "/foo/bar":
rsyncit /foo/bar /backup
Note: This is a possibly significant difference between "rsyncit" and
"rsync". "rsync" seems to put files in different places depending on
whether or not the source path is absolute or relative. "rsyncit" sets
the target subdirectory consistently.
1.3. "rsyncit" was created by OldCoder:
Site: http:https://oldcoder.org/
Mail: [email protected]
GitHub: https://github.com/OldCoder/
Repo: https://github.com/OldCoder/rsyncit.git
The license used for the current version is MIT/X.
----------------------------------------------------------------------
2. Development.
2.1. Source code.
Full source code for the project is provided in the same directory as
this README file. The code consists of a single Perl5 script named
"rsyncit.pl".
2.2. Requirements.
Requirements are simply Linux (or a UNIX system that is reasonably
compatible with Linux), Perl5 5.10.1 or above, and an installed copy
of "rsync". The standard Linux program "less" is recommended but not
required.
2.3. Installation.
No "build" is needed.
To install the package, proceed as follows:
(a) Copy "rsyncit.pl" to wherever you'd like to store the script. If
possible, use one of the directories in PATH.
(b) Remove the ".pl" filename extension and set file permissions to
octal 755. For example:
mv rsyncit.pl rsyncit
chmod 755 rsyncit
----------------------------------------------------------------------
3. Usage.
Usage: rsyncit SourceDir TargetDir
or: rsyncit OPTIONS SourceDir TargetDir
"rsyncit" uses "rsync" to back-up the specified source directory and
its subdirectories to a target subdirectory inside the specified tar-
get directory.
The target subdirectory is transformed into a mirror of the source
directory. As a consequence of this, files already stored in the tar-
get subdirectory will be deleted unless corresponding files exist in
the source directory.
The target subdirectory has the same name as the source directory,
minus any higher-level directory components. For example, the follow-
ing command transforms the directory tree "/backup/bar" into a mirror
of "/foo/bar":
rsyncit /foo/bar /backup
----------------------------------------------------------------------
Backing up "/" (or to "/") is prohibited. "rsyncit" also detects (and
prohibits) cases where the source tree is inside the destination tree
or vice versa.
----------------------------------------------------------------------
By default, the target subdirectory must already exist. This rule is
intended to reduce the chances that files will be backed up to the
wrong place. To override the rule and create directories automatical-
ly, use the option "-d":
rsyncit -d /foo/bar /backup
The word switch "--mkdir" has the same effect as the letter switch
"-d":
rsyncit --mkdir /foo/bar /backup
----------------------------------------------------------------------
By default, "rsyncit" prints some messages but not a complete list of
files as they're copied. For verbose operation, which includes a list
of this type, use the option "-v":
rsyncit -v /foo/bar /backup
The word switch "--verbose" has the same effect as the letter switch
"-v":
rsyncit --verbose /foo/bar /backup
----------------------------------------------------------------------
Single-letter "rsyncit" option switches may be combined. For example,
"-dv" is equivalent to: -d -v. Additionally, option switches may be
placed at any position in the command line. For example, the following
two commands are equivalent:
rsyncit -v /foo/bar /backup
rsyncit /foo/bar /backup -v
----------------------------------------------------------------------
To perform a dry run (i.e., to show what will be done but not actually
do it), use "-n":
rsyncit -n /foo/bar /backup
The "word" switch "--dry-run" (or "--dryrun") has the same effect as
the "letter" switch "-n":
rsyncit --dry-run /foo/bar /backup
Note: "-n" and its aliases don't imply "-v". To produce a verbose ex-
planation of what will be done, add the second switch:
rsyncit -n -v /foo/bar /backup
or: rsyncit -nv /foo/bar /backup
----------------------------------------------------------------------
"rsyncit" supports "rsync"-compatible "--exclude" switches. For exam-
ple, the following command does a backup that excludes the contents of
# directories named "tmp":
rsyncit --exclude="*/tmp/*" -v /foo/bar /backup
If excluded objects are present in the backup tree (for example, from
previous backup operation), "rsyncit" deletes them. "rsyncit" and
"rsync" differ in this respect; "rsync" only does this if the switch
"--delete-excluded" is specified ("rsyncit" sets the switch in quest-
ion automatically).
----------------------------------------------------------------------
To pass "rsync"-level option switches to "rsync", use one or more
"rsyncit"-level option switches of the form:
--rs:"--foo --bar=xyzzy"
or: --rsync:"--foo --bar=xyzzy"
where "--foo --bar=xyzzy" are "rsync"-level switches separated by
spaces. The switches themselves shouldn't include spaces or double
quotes.
Each "--rs" (or "--rsync") switch may specify one or more "rsync"-
level switches. If two or more "--rsync" switches are used, all of the
specified "rsync"-level switches will be passed.
----------------------------------------------------------------------
If multiple backups are done over time using the same source and tar-
get directories, "rsyncit" reuses existing backup files when possible.
The algorithm used for this purpose is good enough for most purposes,
but if files are modified and neither timestamps nor sizes are chang-
ed, modifications of this type may not be detected and backed up. The
option "-c" may be used to fix this, but this option will slow things
down.
The word switch "--checksum" has the same effect as the letter switch
"-c":
rsyncit --checksum /foo/bar /backup
----------------------------------------------------------------------
The letter switch "-f" (or the word switch "--flag") tells "rsyncit"
to manage a "flag" file related to the current backup:
rsyncit -f /foo/bar /backup
The "flag" file has the same pathname as the target subdirectory, but
the string ".rsynced" is added. "rsyncit" deletes the file initially
and creates it at the end if the backup appears to be successful.
Note: If an object with the indicated flag-file name exists and it's
a symbolic link or anything but a regular file, flag-file operations
are skipped. The "-n" (or "--dry-run") option also suppresses flag-
file operations.
----------------------------------------------------------------------
If you'd like to save existing files from the target subdirectory that
are going to be modified or deleted, use the "letter" switch "-b" (or
the "word" switch "--backup"):
rsyncit -b /foo/bar /backup
This option moves the current versions of files that are going to be
modified or deleted to a second backup-directory tree. The second
tree is stored in a directory named "rsyncbak" that's located in the
same directory as the target subdirectory.
For example, "rsyncit -b /foo/bar /backup" will transform "/backup/
bar" into a mirror of "/foo/bar" while saving modified or deleted
files from "/backup/bar" in "/backup/rsyncbak/bar".
----------------------------------------------------------------------
The "word" switch "--go" or "--normal" (there is no corresponding
"letter" switch) is equivalent to:
-bfv
or: -b -f -v
or: --backup --flag --verbose