1
2
3
4
5
6
7
8
9
10
11
12
13
14 """
15 PYBAG - Crossplatform files synchronization and backup portable tools.
16
17 About.
18 ======
19
20 This program implements portable bag and is intended for fast
21 synchronization and backup.
22
23 It let's you use a portable digital storage devace to carry your
24 electronic documents similar to the way you can use a bag to carry
25 paper documents.
26
27 You can synchronize the bag with your original files easily.
28 If a synchronization conflict occurs, it will be reported. You can
29 specify rules for automatic conflict resolution.
30
31 With B{PYBAG}, you can backup files and synchronize any changes
32 made to the original files with the bag. The synchronization process
33 will only copy changed files.
34
35 The program is cross-platform and independent from the OS and
36 filesystem. You may easily synchronize files between Windows and
37 Linux, for example. Symbolic links are supported on all systems (if
38 the OS or filesystem does not support symlinks, then they are emulated).
39
40 This program has a GUI and a command line interface.
41
42 Project page: U{http://pybag.sourceforge.net}
43
44 Bugs trucker: U{http://sourceforge.net/tracker/?group_id=258722&atid=1129796}
45
46 Requiraments.
47 =============
48
49 U{B{Python 2.5.1 ... 2.7 ...}<http://sourceforge.net/projects/python>}.
50
51 For GUI also required:
52
53 U{B{wxPython 2.8.10 + }<http://sourceforge.net/projects/wxpython>}
54
55 General.
56 ========
57
58 I{PYBAG} copy all you files and folders into "./pybagfiles" folder.
59 Information about all entities in "pybagfiles" folder written into DB
60 "./pybag.db" - ziped text file. In DB saves files in bag size, modify date, crc32
61 for all files in bag.
62 In DB files placed in next format::
63 DB_VERSION_MARKER DB_VERSION
64 F SIZE MDATE CRC32 path_to_file1_in_pybagfiles link_point1
65 F SIZE MDATE CRC32 path_to_file2_in_pybagfiles link_point2
66 ... and so on.
67 All lines must end with newline, where:
68 - "F" - flag: d-directory, f-file, s-symlink, ''-is empty entry.
69 - "SIZE" - file size in decimal or "-" for directories.
70 - "MDATE" - modification date in YYYY/MM/DD-HH:mm:ss.
71 - "CRC32" - crc32 in hex if exist or "-".
72 - "path_to_file" - bag path to item into pybagfiles.
73 - "link_point" - if item link then it'spoint, otherwise '-'.
74
75 Also have "pybag.cfg" file where saved preferences.
76 Format is:
77 - B{[root]} global preference:
78 - B{ignore} = global ignores I{default = ''-process all files}.
79 Separated commas ','. Pattern as fnmatch.
80 - B{symlink} = copy | ignore | copynoemul| ignorenoemul. I{default = copy}.
81 - B{compare} = stat | crc32. Compare
82 method, "stat" - by size and modify date, "crc32" - by crc32,
83 I{default = stat}.
84 - B{backup} = 0 | 1. I{Default = 0}
85 - B{mddelta} = Time differense in seconds for assign files equal then
86 compare modify date (float). Default is 1.0 sec.
87 - B{nextid} = next free sequence id (integer).
88 - B{r###} = C{F path} where "F" - flag (f=file, d=directory, s=symlink),
89 "path" - path to root ###, where ### is root id. Last
90 part of path is a start path in pybagfiles folder.
91 - B{emulation} = 0 | 1.
92 - B{verbosity} - verbosity level (-1 .. 5).
93 - B{debug} = 0 | 1.
94 - B{logging} = 0 | 1.
95 - B{colorize} = 0 | 1.
96 - B{outfilter} - outfilter for sync command.
97
98 - B{[r###_pref]} - local preference if need I{default none}:
99 - B{ignore} = ignore list. Separated commas ','. Pattern as fnmatch.
100 - B{symlink} = as above.
101 - B{compare} = as above.
102 - B{backup} = as above.
103 - B{selectdefault} = 0 | 1.
104
105 - B{[GUI]} - GUI preference:
106 - B{writecolsatexit} = Write column position when exit from program (
107 only if emuletion turn off). 0 | 1. Default is 0.
108 - B{output} - Show output window. 0 | 1. Default is 1.
109 - B{showtips} - Show tips window at start up. 0 | 1. Default is 1.
110 - B{column#} - Columns preferences. "#" is a column order. Format is:
111 C{column0 = name, visible, width}. Where C{cfgname} - is a column name,
112 C{visible} - column visibility 0 or 1, C{width} - column width in pixels (
113 from 0 to 2000). Allowed column names is next:
114 - C{stateicon} - Item state icon.
115 - C{actionicon} - Item action icon.
116 - C{err} - Item errors mark (B{e} - error, B{c} - conflict, B{w} - warning).
117 - C{forced} - Forced state (B{!} - item action is forced).
118 - C{dir} - Action direction:
119 - C{<<<} - New in origin, copy to bag.
120 - C{>>>} - New in bag, copy o origin.
121 - C{<--} - Changed in origin, copy to bag.
122 - C{-->} - Changed in bag, copy to origin.
123 - C{xxx} - Delete item.
124 - C{---} - Ignored item.
125 - C{===} - Unchanged item.
126 - C{<==} - Unchanged item, time shift in bag.
127 - C{==>} - Unchanged item, time shift in origin.
128 - C{***} - Error in filter and programm. Note author if
129 this situation appears.
130 - C{path} - Item path in bag.
131 - C{desc} - Description.
132 - C{type} - Item type:
133 - C{f} - file,
134 - C{d} - directory,
135 - C{s} - symlink,
136 - C{ } empty - unknown (or may be ignored).
137 - C{mdatedb} - Item date in DB, float.
138 - C{gmdatedb} - Item date in DB, GMT.
139 - C{lmdatedb} - Item date in DB, Local.
140 - C{crc32db} - Item CRC32 sum in DB.
141 - C{sizedb} - Item size in DB, bytes.
142 - C{symlinkdb} - Symlink in DB.
143 - C{mdatebag} - Item date in bag, float.
144 - C{gmdatebag} - Item date in bag, GMT.
145 - C{lmdatebag} - Item date in bag, Local.
146 - C{crc32bag} - Item CRC32 sum in bag.
147 - C{sizebag} - Item size in bag, bytes.
148 - C{symlinkbag} - Symlink in bag.
149 - C{mdateorigin} - Item date in origin, float.
150 - C{gmdateorigin} - Item date in origin, GMT.
151 - C{lmdateorigin} - Item date in origin, Local.
152 - C{crc32origin} - Item CRC32 sum in origin.
153 - C{sizeorigin} - Item size in origin, bytes.
154 - C{symlinkorigin} - Symlink in origin.
155 - C{timeshift} - Time shift:
156 - C{b} - Item in bag is time shifted,
157 - C{o} - Item in origin is timeshifted,
158 - C{ } empty - Item not time shifted.
159 - B{filter_####} = 0 or 1. Filter with name #### allowed or disabled.
160 Filters may be next:
161 - C{filter_ok} - synchronization OK,
162 - C{filter_bag} - Item action to bag,
163 - C{filter_orig} - Item action to origin,
164 - C{filter_del} - Delete item,
165 - C{filter_ch} - Item was changed,
166 - C{filter_new} - Item is new,
167 - C{filter_err} - Error in item,
168 - C{filterconf} - Conflict in item,
169 - C{filter_warn} - Warning in item,
170 - C{filter_forced} - Item action is forced,
171 - C{filter_unch} - Item is unchanged,
172 - C{filter_file} - Item type is file,
173 - C{filter_dir} - Item type is directory,
174 - C{filter_sym} - Item type is symlink,
175 - C{filter_unk} - Item type is unknown,
176 - C{filter_ign} - Item is ignored.
177 - C{filter_ts} - Item is timeshifted.
178
179 Directory structure.
180 --------------------
181
182 - B{doc} - Documentation directory.
183
184 - B{api} - API documentation.
185 - B{manual} - User manual.
186
187 - B{pybagfiles} - Directory where files saved in bag.
188 - B{pybag.db} - File list database, ziped text.
189 - B{pybag.cfg} - Configuration file.
190 - B{pybag.log} - Log file.
191 - B{...~} - File ends with tilda "~" is backup.
192
193 Timeshift.
194 ----------
195
196 In several conditions (for example when synchronize Windows and Flash-FAT)
197 you may have problems with daylight saving. Details - you synchronize all you
198 files in evening and in night was changet time for daylight saving. In the morning
199 you found that all you files was changed (modification date between bag and
200 origin different about 3600 seconds)!!! This is bad do copy all files.
201 You can use "timeshift" operation instead real copying. Timeshift is
202 only change modification (and access) date. "Timeshift to bag" mean that for all
203 marked files in bag will be set modification date same as in origin.
204 "Timeshift to origin" mean that for all
205 marked files in origin will be set modification date same as in bag.
206
207 In CLI interface you can use "-y" option for set timeshift manualy or
208 use action "tsbag", "tsorigin", "tsreset" for set (reset) timeshift by template.
209 In GUI you can use menu "Action->Timeshift-> ... " for set timeshift by template.
210 Set timeshift by template means that you specify file which needs in timeshift and
211 it become template - calculated time difference from this file used for all other files.
212
213 Command line.
214 =============
215
216 C{B{ pybag.py --command -option1 -option2 argument1 argument2 ... }}
217
218 I{B{Warning:} At once may be executed only one command.}
219
220 I{B{Recomendation:} Use emulation mode B{-m1} befor real files
221 operation (exclude B{--dist}). For real file operation you need use
222 option B{-m0}.}
223
224 Commands.
225 ---------
226
227 - C{B{ --gui }}
228
229 Open GUI. Without commands also run GUI.
230
231 - C{B{ --add {-k -s -e -b -x -rDIR} path1 {path2 ...} }}
232
233 Add new roots to bag. If option I{-k -e -s -b} is not specified then will
234 be used it's default values (symlink ignore, all files, stat comparison, no backup).
235 In next step you must synchronize pybag with I{sync}.
236 Options in this command set properties for added roots and for next
237 synchronizations. In the future you can manualy edit pybag.cfg for
238 change root properties or use GUI interface.
239
240 Options:
241
242 - C{B{ -kFLAG }}
243
244 Symlink action:
245
246 - B{ c } or B{copy} - copy symlink, emulate symlink.
247 - B{ i } or B{ignore} - ignore symlink, emulate symlink. It is default.
248 - B{ cn } or B{copynoemul} - copy symlink, do not emulate symlink.
249 - B{ in } or B{ignorenoemul} - ignore symlink, do not emulate symlink.
250
251 - C{B{ -sFLAG }}
252
253 Set compare method for files comparison.
254 FLAG is comparison method:
255
256 - C{B{ stat }} or I{no flag or empty} - Use only stat information
257 (size, modify date) - default. For directory modify date do
258 not used.
259 - C{B{ crc32 }} - Use CRC32 check then syncronize.
260
261 - C{B{ -eFILEMASK }}
262
263 Exclude from process all files and folders liked FILEMASK:
264 - Wildcards (as fnmatch) separated commas: C{"*.bak,*.pyc"}.
265 - RegExp if FILEMASK starts with "B{!}": C{"!(.*\.bak$)|(.*\.pyc$)"}.
266 You may get few optins "-e".
267 Default all files processed.
268
269 - C{B{ -bFLAG }}
270
271 Backup mode for this root:
272
273 - B{ 0 } - No backup (default).
274 - B{ 1 } - This is will be backup copy of origin.
275 In synchronization always used direction "bagall".
276 Backup copy synchronize in up 2 times faster then standart.
277
278 - C{B{ -xDEF }}
279
280 Mark roots as default:
281
282 - B{ 1 } - Mark as default.
283 - B{ 0 } - Do not mark.
284
285 If not specified then mark all roots as default.
286
287 - C{B{ -rDIR }}
288
289 Add all items from directory DIR as roots.
290 You may get few optins "-r".
291
292 - C{B{ --remove root1 {root2 ...} }}
293
294 Remove roots from bag.
295
296 - C{B{ --dist {-z} {-i} {-x} {-a} {-rROOT1 ...} {path1} }}
297
298 Distribute PYBAG program to specified location. This do clear distribute
299 without any files in current bag. If options I{-r} or I{-a} is given then in
300 destination path also adjust pybag.cfg to
301 point original to this (current) point.
302 If you point "path1" into other pybag then adding all to it.
303 If you initialize I{-i} then you may not specify "path1".
304 With other options "path1" is required.
305
306 Options:
307
308 - C{B{ -z }}
309
310 Copy all additional files (manual, license and etc.). Create folder
311 "pybagfiles" if need. Not copied roots.
312
313 - C{B{ -i }}
314
315 Initialize - Create "pybagfiles" directory, configuration file and
316 DB file. If "path1" not specified then initialize current location,
317 overwise into specified location.
318 Create only absent items, do not change exists. If "path1" not exists
319 then try create this directory.
320
321 - C{B{ -a }}
322
323 Copy all roots (if given this option, then options "-r" mark roots for miss).
324
325 - C{B{ -xDEF }}
326
327 Select roots for distribute:
328
329 - B{ all } - All roots.
330 - B{ default} - Default roots.
331
332 If not specified then select only default roots.
333 This options ignored when specified "-a" or "-r" option.
334
335 - C{B{ -rROOT }}
336
337 Distribute only specified roots (if option B{-a} given, then mark not copied roots).
338
339 - C{B{ --sync { -fFILE } {-xDEF} {-dDIR} {-dDIR} {-sMDDELTA} { -pA } { -bFLAG } { -gOUTFILTER } { -yFLAGVALUE } {path1} }}
340
341 Synchronize current bag with original files. If "path1" specified
342 then syncronize with specified location (path1). If no "f" option given
343 then try sync all pybag roots in path "path1/root". if specified
344 "f" then "path1" must correspond path in option. After comparing you will be prompt
345 for continue synchronization and need answer B{y} for continue or B{n} for cancel.
346
347 Options:
348
349 - C{B{ -fFILE }}
350
351 Syncronize or copy only specified file "FILE", where FILE is a relative path
352 to "/pybagfiles".
353
354 For example: you have file C{"pybag/pybagfiles/project/bin/file1.py"},
355 for synchronize you must write C{pybag --sync -f"project/bin/file1.py"}.
356
357 - C{B{ -xDEF }}
358
359 Select roots for synchronization:
360
361 - B{ all } - All roots.
362 - B{ default} - Default roots.
363
364 If not specified then select only default roots.
365 This options ignored when specified "-f" option.
366
367 - C{B{ -dDIR }}
368
369 Direction for synchronization copy if conflicts occurs:
370
371 - B{ bag } - write changed files into bag.
372 - B{ origin } - write changed files into copy or original location.
373 - B{ newer } - newer files overwrite older.
374 - B{ older } - older files overwrite newer.
375 - B{ no } - do not change files. Is default.
376 - B{ bagall } - write all changes from origin to bag.
377 - B{ originall } - write all changes from bag to origin.
378 - B{ bagcopy } - copy all changes to bag, but do not delete from bag anything.
379 - B{ origincopy } - copy all changes to origin, but do not delete from origin anything.
380
381 B{newer} and B{older} may be given with B{bag} and B{origin}
382 simulteniously (for example C{ -dbag -dnewer }).
383 First will be checked B{newer} and B{older},
384 after - used B{bag} and B{origin}.
385
386 B{ATTENTION: Do not mix other direction flags, result may be umbigous.}
387
388 - C{B{ -sMDDELTA }}
389
390 Set modify date delta in seconds (float number). If dates
391 different less then MDDELTA then they assign equal.
392 Overrade configuration file settings.
393
394 - C{B{ -bFLAG }}
395
396 Backup option:
397
398 - B{ 0 } - Standart backup, is default, read only origin.
399 This mode is fast - read only origin files.
400 - B{ 1 } - Synchronization mode, read origin and bag and synchronize.
401
402 - C{B{ -pA }}
403
404 Autoanswer for question ( I{"Continue synchronization?"}):
405
406 - B{ y } - yes, continue.
407 - B{ n } - no, cancel.
408
409 - If no autoanswer specified then you can use I{interactive menu}:
410
411 - B{d} DIR DIR - change rules for autoconflict resolution (after change direction
412 comparison will be repeated, and menu displayed again).
413 - B{m} FLAG - change emulation level.
414 - B{t} FLAG - change debug level.
415 - B{v} FLAG - change verbosity level.
416 - B{y} - continue syncronization.
417 - B{n} - cancel syncronization.
418 - B{g} OUTFILTER - change output filter.
419 - B{r} - repeat report.
420 - B{a} #ACTION FILTER - manual force action ACTION with paths FILTER. Action
421 may be next:
422 - B{delete} - delete item,
423 - B{bag} - copy to bag or ignore if origin deleted,
424 - B{origin} - copy to origin or ignore if bag deleted,
425 - B{skip} - skip action (mark unchanged),
426 - B{restore} - restore automatic action.
427 - B{tsbag} - timeshift to bag, FILTER used as template.
428 - B{tsorigin} - timeshift to origin, FILTER used as template.
429 - B{tsreset} - reset timeshift.
430 "#" mean "+" or "-" or nothing. "+" - is interactive action, ask
431 for each path user confirmation. "-" - do not list paths and not
432 need in confirmation. Nothing - is list paths but not need in confirmation.
433 After using C{ts....} action items will be recompared and all actions will be reset.
434 Use first C{ts...} action and after other actions.
435
436 - C{B{ -gOUTFILTER}}
437
438 Output filter - difine which operation will be printed.
439 Default is C{-gI{sbonhdftwce1234}} - display in report all operation with
440 new, copied, deleted, forced and not forced files, errors, conflicts
441 and warnings for all direction in short format.
442 Filter options:
443
444 - B{x} - Do not show report.
445 - B{l} - Long format of report: '%%(forced)s %%(dir)s %%(err)s [%%(path)s]\\n\\t%%(desc)s'.
446 - B{s} - Short format of report: '%%(forced)s %%(dir)s %%(err)s [%%(path)s]'.
447 - B{p} - Old (as in previous version) format: '\\t[%(path)s]-->\\n\\t == "%%(desc)s".'.
448 - B{m..FORMAT..} - Manual specified format as print function. "B{..}" - is separator (may be any two symbols).
449 Available keywords is:
450
451 - B{err} - "w", "c", "e" or " " - warning,
452 conflict, error or nothing.
453 - B{forced} - "!" or " " - Operation forced or not.
454 - B{path} - Item path (in OS format).
455 - B{desc} - Description.
456 - B{type} - "f", "d", "s" ,"u" - Item type, file,
457 directory, symlink or unknown.
458 - B{mdatedb} - Modification date in DB, seconds.
459 - B{gmdatedb} - GMT modification date in DB, "YYYY-DD-MM HH-MM-SS".
460 - B{lmdatedb} - Local modification date in DB, "YYYY-DD-MM HH-MM-SS".
461 - B{crc32db} - CRC32 in DB, "0xFFFFFFFF".
462 - B{sizedb} - Size in DB.
463 - B{symlinkdb} - Iflink point DB, "-" if not symlink.
464 - B{mdatebag} - Modification date in bag, seconds.
465 - B{gmdatebag} - GMT modification date in bag, "YYYY-DD-MM HH-MM-SS".
466 - B{lmdatebag} - Local modification date in bag, "YYYY-DD-MM HH-MM-SS".
467 - B{crc32bag} - CRC32 in bag, "0xFFFFFFFF".
468 - B{sizebag} - Size in bag.
469 - B{symlinkbag} - Iflink point bag, "-" if not symlink.
470 - B{mdateorigin} - Modification date in origin, seconds.
471 - B{gmdateorigin} - GMT modification date in origin, "YYYY-DD-MM HH-MM-SS".
472 - B{lmdateorigin} - Local modification date in origin, "YYYY-DD-MM HH-MM-SS".
473 - B{crc32origin} - CRC32 in origin, "0xFFFFFFFF".
474 - B{sizeorigin} - Size in origin.
475 - B{symlinkorigin} - If link point origin, "-" if not symlink.
476 - B{dir} - Direction, displayed by next symbols:
477 - C{<<<} - New in origin, copy to bag.
478 - C{>>>} - New in bag, copy o origin.
479 - C{<--} - Changed in origin, copy to bag.
480 - C{-->} - Changed in bag, copy to origin.
481 - C{xxx} - Delete item.
482 - C{---} - Ignored item.
483 - C{===} - Unchanged item.
484 - C{<==} - Unchanged item, time shift in bag.
485 - C{==>} - Unchanged item, time shift in origin.
486 - C{***} - Error in filter and programm. Note author if
487 this situation appears.
488 - B{timeshift} - Time shift:
489 - C{b} - Item in bag is time shifted,
490 - C{o} - Item in origin is time shifted,
491 - C{ } empty - Item not shifted.
492
493 - B{z00} - List report by I{n} items per page.
494 - B{b} - Operation with direction to bag.
495 - B{o} - Operation with direction to origin.
496 - B{n} - Operation with new files.
497 - B{h} - Operation with changed (copied) files.
498 - B{d} - Operation with deleted files.
499 - B{y} - Timeshift operations.
500 - B{i} - Ignored files.
501 - B{u} - Unchanged files.
502 - B{f} - Forced action.
503 - B{w} - Warnings.
504 - B{c} - Conflicts.
505 - B{e} - Errors.
506 - B{1} - Files.
507 - B{2} - Directories.
508 - B{3} - Symlinks.
509 - B{4} - Unknown (normaly this is must not be).
510 - B{r..PATT..} - Path wilds or regexp filter. If not specified then all displayed.
511
512 - C{B{ -yFLAGVALUE }}
513
514 Timeshift option - set predifined time shift. B{FLAG} is next:
515
516 - B{b} - Time shift in bag.
517 - B{o} - Time shift in origin.
518
519 B{VALUE} may be next:
520
521 - B{#FILTER}, where FILTER is "wilds" or "!regexp" filter
522 to find item which will be used as template for time shift.
523 Example: C{-yb#*} - time shift to bag and use first found file as template.
524 - B{BAGSHIFT#ORIGINSHIFT} - Set up manualy time shifts for bag and origin.
525 Example: C{-yb-3600#0} - time shift to bag and set bag shift to "-3600" and origin to "0.0".
526 BAGSHIFT and ORIGINSHIFT used for get modification date for files.
527 For files in bag modification date calculated as (bagfile.mdate + BAGSHIFT),
528 for files in origin modification date calculated as (originfile.mdate + ORIGINSHIFT).
529 If no timeshift set then modification date equal file.mdate.
530
531 - C{B{ --relocate -rROOT=NEWPATH { -rROOT=NEWPATH ...} }}
532
533 Realocate root. Replace origin path for ROOT by new NEWPATH.
534
535 - C{B{ --stat {-xDEF} {-rROOT1 ...} }}
536
537 Show statistic about bag files for all roots or only for specified with
538 option B{-r}.
539
540 In statistic shown for each root and for all summary roots at end:
541
542 - Files count,
543 - Directory count,
544 - Symlink count,
545 - Summary items count,
546 - Summary items size,
547 - Database size (for roots summary).
548
549 Options:
550
551 - C{B{ -rROOT }}
552
553 Show statistic only about specified roots.
554
555 - C{B{ -xDEF }}
556
557 Select roots:
558
559 - B{ all } - All roots.
560 - B{ default} - Default roots.
561
562 If not specified then select all roots.
563 This options ignored when specified "-r" option.
564
565 - C{B{ --cleandb }}
566
567 Clean DB from old records (old roots which already removed).
568
569 - C{B{ --help, -h, --usage }}
570
571 Display help information.
572
573 - C{B{ --version }}
574
575 Show version.
576
577 - C{B{ --author }}
578
579 Show author.
580
581 - C{B{ --copyright }}
582
583 Show copyright.
584
585 - C{B{ --license }}
586
587 Show license.
588
589 - C{B{ --about }}
590
591 About information.
592
593 - C{B{ --debug {name ...} }}
594
595 Set PYBAG_DEBUG and PYBAG_LOG to True and call L{cli._debug} function.
596 For debug purpouse only. Must be first in options list. If get I{name}
597 then call only this methods ("_test_name") if exists.
598 Right tests will be only into source distribution. In copy files
599 (for example distributed with --dist) number tests will be fail.
600
601 Common options:
602 ---------------
603
604 This options may be used for all command.
605
606 - C{B{I{ -vLEVEL }}}
607
608 Set verbosity level (0 - no verbosity) B{0 ... 4}.
609 Default assign B{3}.
610
611 - B{ -1 } - No output. Only log file.
612 - B{ 0 } - Only global errors.
613 - B{ 1 } - Very small output, only about success and errors.
614 - B{ 2 } - As B{1} and conflicts.
615 - B{ 3 } - Normal output. As B{2} and warnings.
616 - B{ 4 } - Large output. As B{3} and file operation.
617 - B{ 5 } - Huge output. As B{4} and logging.
618
619 - C{B{I{ -lFLAG }}}
620
621 Enable B{1} or disable B{0} logging. FLAG may be 0 or 1.
622 Default assign B{1}.
623
624 - C{B{I{ -tFLAG }}}
625
626 Enable B{1} or disable B{0} debug output. FLAG may be 0 or 1.
627 Default assign B{0}.
628
629 - C{B{I{ -mFLAG }}}
630
631 Enable B{1} or disable B{0} emulation. FLAG may be 0 or 1.
632 Do not realy perform write operation. Do all actions as
633 real command but do not change any files.
634 Default assign B{0}.
635 Usually this option use with I{-l} or I{-t} options for logging
636 emulation result.
637
638 - C{B{I{ -cFLAG }}}
639
640 Enable B{1} or disable B{0} colorize output. FLAG may be 0 or 1.
641 Default assign B{1}.
642
643 GUI.
644 ====
645
646 See GUI description in manual.
647
648 """
649
650
651
652
653
654
655
656 from version import __version__, __year__, __year_start__
657
658
659
660 __license__ = u"""
661 Copyright (c) %s ... %s, Mazhugin Aleksey
662
663 All rights reserved.
664
665 Redistribution and use in source and binary forms, with or without modification,
666 are permitted provided that the following conditions are met:
667
668 * Redistributions of source code must retain the above copyright notice,
669 this list of conditions and the following disclaimer.
670 * Redistributions in binary form must reproduce the above copyright notice,
671 this list of conditions and the following disclaimer in the documentation
672 and/or other materials provided with the distribution.
673 * Neither the name of the Mazhugin Aleksey nor the names of its contributors may be
674 used to endorse or promote products derived from this software without
675 specific prior written permission.
676
677 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
678 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
679 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
680 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
681 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
682 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
683 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
684 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
685 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
686 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
687 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
688 """ % (__year_start__, __year__)
689
690
691 __header__ = u"""<G>
692 ###########################################
693 # *** P Y B A G *** #
694 # version: %s #
695 # Copyright (c) %s, Mazhugin Aleksey #
696 ###########################################
697 </G>""" % (__version__, __year__)
698
699
700 __about__ = u"""
701 <C>About.</C>
702 <C>------------------------------------</C>
703 <g>PYBAG</g> - Crossplatform files synchronization and backup portable tools.
704
705 This program implements portable bag and is intended for fast
706 synchronization and backup.
707
708 It let's you use a portable digital storage devace to carry your
709 electronic documents similar to the way you can use a bag to carry
710 paper documents.
711
712 You can synchronize the bag with your original files easily.
713 If a synchronization conflict occurs, it will be reported. You can
714 specify rules for automatic conflict resolution.
715
716 With <g>PYBAG</g>, you can backup files and synchronize any changes
717 made to the original files with the bag. The synchronization process
718 will only copy changed files.
719
720 The program is cross-platform and independent from the OS and
721 filesystem. You may easily synchronize files between Windows and
722 Linux, for example. Symbolic links are supported on all systems (if
723 the OS or filesystem does not support symlinks, then they are emulated).
724
725 This program has a GUI and a command line interface.
726
727 Project page: http://pybag.sourceforge.net
728
729 Bugs trucker: http://sourceforge.net/tracker/?group_id=258722&atid=1129796
730
731 IF YOU LIKE PYBAG AND FOUND IT USEFUL WHEN YOU CAN DONATE TO AUTHOR
732 SOME MONEY ON PROJECT PAGE: http://pybag.sourceforge.net.
733
734 If you do not want donate money then you can treat the
735 author cap of coffee and pizza.
736
737 THANK YOU.
738
739 Requiraments.
740 =============
741
742 Python 2.5.1 ... 2.7 ... - http://sourceforge.net/projects/python.
743
744 For GUI also required:
745 wxPython 2.8.10 + - http://sourceforge.net/projects/wxpython.
746
747 """
748
749
750 _usage = u"""
751 <C>Usage.</C>
752 <C>------------------------------------</C>
753
754 Command line help. For GUI see manual.
755
756 <W>pybag.py --command -option1 -option2 argument1 argument2 ...</W>
757
758 Warning: At once may be executed only one command.
759
760 Recomendation: Use emulation mode "-m1" befor real files
761 operation (exclude "dist").
762
763 <g>Commands:</g>
764 <g>---------</g>
765
766 <M>--gui</M>
767
768 Open GUI.
769
770
771 <M>--add {-k -s -e -b -x -rDIR} path1 {path2 ...}</M>
772
773 Add new roots ("path"s) to bag. After adding roots you
774 must syncronize for real copying.
775
776 <y>-kFLAG</y> - Symlink action:
777 <c>c</c>, <c>copy</c> - copy symlink.
778 <c>cn</c>, <c>copynoemul</c> - copy symlink, no emulation.
779 <c>i</c>, <c>ignore</c> - ignore symlink. It is default.
780 <c>in</c>, <c>ignorenoemul</c> - ignore symlink, no emulation.
781
782 <y>-sFLAG</y> - Set compare method for files comparison.
783 FLAG is comparison method:
784 <c>stat</c> or no flag or empty - Use only stat information
785 size, modify date - default. For directory modify
786 date do not used.
787 <c>crc32</c> - Use CRC32 check then syncronize.
788
789 <y>-eFILEMASK</y>
790 Exclude from process all files and folders liked FILEMASK
791 (as fnmatch separated commas). You may get few optins "-e".
792 Default all files processed.
793
794 <y>-bFLAG</y>
795 Backup mode for this root. 0 - No backup (default),
796 1 - backup (one way fast synchronization, to bag).
797
798 <y>-xDEF</y>
799 Mark roots as default:
800 <c>1</c> - Mark roots as default.
801 <c>0</c> - Roots not default.
802 If not specified then mark roots as default.
803
804 <y>-rDIR</y>
805 Add all items from directory DIR as roots.
806 You may get few optins "-r".
807
808
809 <M>--remove root1 {root2 ...}</M>
810
811 Remove roots from bag.
812
813
814 <M>--dist {-z} {-i} {-x} {-a} {-rROOT1 ...} {path1}</M>
815
816 Distribute PYBAG program to specified location. This do clear distribute
817 without any files in current bag. If options "-r" or "-a" is given then in
818 destination path also adjust pybag.cfg to
819 point original to this (current) point.
820 If you point "path1" into other pybag then adding all to it.
821 If you initialize "-i" then you may not specify "path1".
822 With other options "path1" is required.
823
824 <y>-z</y>
825 Copy all additional files (manual, license and etc.). Create folder
826 "pybagfiles" if need. Not copied roots.
827
828 <y>-i</y>
829 Initialize - Create "pybagfiles" directory, configuration file and
830 DB file. If "path1" not specified then initialize current location,
831 overwise into specified location.
832 Create only absent items, do not change exists. If "path1" not exists
833 then try create this directory.
834
835 <y>-xDEF</y>
836 Select roots for distribute:
837 <c>all</c> - All roots.
838 <c>default</c> - Default roots.
839 If not specified then distribute only default roots.
840 This options ignored when specified "-r" or "-a" options.
841
842 <y>-a</y>
843 Copy all roots (if given this option, then options "-r" mark not copied roots).
844
845 <y>-rROOT</y>
846 Distribute only specified roots (if option "-a" given, then mark not copied roots).
847
848
849 <M>--sync { -fFILE } {-xDEF} {-dDIR} {-dDIR} {-sMDDELTA} { -pA } { -bFLAG } {-gOUTFILTER} {-yFLAGVALUE} {path1}</M>
850
851 Synchronize current bag with original files. If "path1" specified
852 then syncronize with specified location (path1). If no "f" option given
853 then try sync all pybag roots in path "path1/root". if specified
854 "f" then "path1" must correspond path in option. After comparing you
855 will be prompt for continue synchronization and need answer "y"
856 for continue or "n" for cancel.
857
858 <y>-fFILE</y>
859 Syncronize or copy only specified file "FILE", where FILE
860 is a relative path to "/pybagfiles".
861 For example: you have file "pybag/pybagfiles/project/bin/file1.py",
862 for synchronize you must write
863 pybag --sync -f"project/bin/file1.py"
864
865 <y>-xDEF</y>
866 Select roots for synchronization:
867 <c>all</c> - All roots.
868 <c>default</c> - Default roots.
869 If not specified then select only default roots.
870 This options ignored when specified "-f" option.
871
872 <y>-dDIR</y>
873 Direction for synchronization copy if conflicts occurs:
874 <c>bag</c> - write changed files into bag.
875 <c>origin</c> - write changed files into copy or original location.
876 <c>newer</c> - newer files overwrite older.
877 <c>older</c> - older files overwrite newer.
878 <c>no</c> - do not change files. Is default.
879 <c>bagall</c> - write all changes from origin to bag.
880 <c>originall</c> - write all changes from bag to origin.
881 <c>bagcopy</c> - copy all changes to bag, but do not delete from
882 bag anything.
883 <c>origincopy</c> - copy all changes to origin, but do not delete
884 from origin anything.
885
886 "newer" and "older" may be given with "bag" and "origin"
887 simulteniously (for example -dbag -dnewer).
888 First will be checked "newer" and "older",
889 after used "bag" and "origin".
890
891 <W>ATTENTION</W>: Do not mix other direction flags, result may be umbigous.
892
893 <y>-sMDDELTA</y>
894 Set modify date delta in seconds (float number). If dates
895 different less then MDDELTA then they assign equal.
896 Overrade configuration file settings.
897
898 <y>-bFLAG</y>
899 Backup option:
900 <c>0</c> - Standart backup (one way), is default.
901 This mode is fast - read only origin files.
902 <c>1</c> - Synchronization mode - read bag and origin and synchronize.
903
904 <y>-pA</y>
905 Autoanswer for question "Continue synchronization?":
906 <c>y</c> - yes, continue.
907 <c>n</c> - no, cancel.
908
909 - If no autoanswer specified then you can use interactive menu:
910
911 <r>d DIR DIR</r> - change rules for autoconflict resolution (after
912 change direction comparison will be repeated, and menu
913 displayed yet).
914 <r>m FLAG</r> - change emulation level.
915 <r>t FLAG</r> - change debug level.
916 <r>v FLAG</r> - change verbosity level.
917 <r>y</r> - continue syncronization.
918 <r>n</r> - cancel syncronization.
919 <r>g OUTFILTER</r> - change output filter.
920 <r>r</r> - repeat report.
921 <r>a #ACTION FILTER</r> - manual force action ACTION with paths FILTER.
922 Action may be next:
923 <B>delete</B> - delete item,
924 <B>bag</B> - copy to bag or ignore if origin deleted,
925 <B>origin</B> - copy to origin or ignore if bag deleted,
926 <B>skip</B> - skip action (mark unchanged),
927 <B>restore</B> - restore atomatic action.
928 <B>tsbag</B> - time shift in bag.
929 <B>tsorigin</B> - timeshift in origin.
930 <B>tsreset</B> - reset timeshift.
931 "<r>#</r>" mean "<B>+</B>" or "<B>-</B>" or nothing. "+" - is interactive action, ask
932 for each path user confirmation. "-" - do not list paths and not
933 need in confirmation. Nothing - is list paths but not need
934 in confirmation. After using ts... action items will be recompared.
935 First use ts... action and after it use other actions.
936
937 <y>-gOUTFILTER..MANUALFORMAT..PATHFILTER..</y>
938
939 Output filter - difine which operation will be printed.
940 Default is C{-gI{sbonhdftwce1234}} - display in report all
941 operation with new, copied, deleted, forced and not forced files,
942 errors, conflicts and warnings for all
943 direction in short format.
944
945 <c>x</c> - Do not show report.
946 <c>l</c> - Long format of report: '%%(forced)s %%(dir)s %%(err)s [%%(path)s]\\n\\t%%(desc)s'.
947 <c>s</c> - Short format of report: '%%(forced)s %%(dir)s %%(err)s [%%(path)s]'.
948 <c>p</c> - Old (as in previous version) format: '\\t[%%(path)s]-->\\n\\t == "%%(desc)s".'.
949 <c>m..FORMAT..</c> - Manual specified format as in "print" function (see manual).
950 <c>z00</c> - List report by n items per page.
951 <c>b</c> - Operation with direction to bag.
952 <c>o</c> - Operation with direction to origin.
953 <c>n</c> - Operation with new files.
954 <c>h</c> - Operation with changed (copied) files.
955 <c>d</c> - Operation with deleted files.
956 <c>i</c> - Ignored files.
957 <c>u</c> - Unchanged files.
958 <c>f</c> - Forced action.
959 <c>y</c> - Time shift operations.
960 <c>w</c> - Warnings.
961 <c>c</c> - Conflicts.
962 <c>e</c> - Errors.
963 <c>1</c> - Files.
964 <c>2</c> - Directories.
965 <c>3</c> - Symlinks.
966 <c>4</c> - Unknown (normaly this is must not be).
967 <c>r..PATT..</c> - Path wilds or regexp filter. If not specified
968 then all displayed.
969
970 <y>-yFLAGVALUE</y>
971 Timeshift option - set predifined time shift. "FLAG" is next:
972 <c>b</c> - Time shift in bag.
973 <c>o</c> - Time shift in origin.
974 "VALUE" may be next:
975 "#FILTER", where FILTER is "wilds" or "!regexp" filter
976 to find item which will be used as template for time shift.
977 Example: "-yb#*" - time shift to bag and use first found
978 file as template.
979 "BAGSHIFT#ORIGINSHIFT" - Set up manualy time shifts for bag and
980 origin.
981 Example: "-yb-3600#0" - time shift to bag and set bag shift
982 to "-3600" and origin to "0.0".
983 BAGSHIFT and ORIGINSHIFT used for get modification date for
984 files. For files in bag modification date calculated as
985 (bagfile.mdate + BAGSHIFT), for files in origin modification
986 date calculated as (originfile.mdate + ORIGINSHIFT).
987 If no timeshift set then modification date equal file.mdate.
988
989 <M>--relocate -rROOT=NEWPATH { -rROOT=NEWPATH ...}</M>
990
991 Realocate root. Replace origin path for ROOT by new NEWPATH/
992
993 <M>--stat {-xDEF} {-rROOT1 ...}</M>
994
995 Show statistic about bag files for all roots or only for specified with
996 option "-r".
997
998 <y>-xDEF</y>
999 Select roots:
1000 <c>all</c> - All roots.
1001 <c>default</c> - Default roots.
1002 If not specified then select all roots.
1003 This options ignored when specified "-r" option.
1004
1005 In statistic shown for each root and for all summary roots at end:
1006 - Files count,
1007 - Directory count,
1008 - Symlink count,
1009 - Summary items count,
1010 - Summary items size,
1011 - Database size (for roots summary).
1012
1013 <y>-rROOT</y>
1014 Show statistic only about specified roots.
1015
1016 <M>--cleandb</M>
1017
1018 Clean DB from old records (old roots which already removed).
1019
1020 <M>--help</M>
1021 <M>-h</M>
1022 <M>--usage</M>
1023
1024 Display help information.
1025
1026
1027 <M>--version</M>
1028
1029 Show version.
1030
1031
1032 <M>--author</M>
1033
1034 Show author.
1035
1036
1037 <M>--copyright</M>
1038
1039 Show copyright.
1040
1041
1042 <M>--license</M>
1043
1044 Show license.
1045
1046
1047 <M>--about</M>
1048
1049 About information.
1050
1051
1052 <M>--debug {name ...}</M>
1053
1054 Set PYBAG_DEBUG and PYBAG_LOG to True and call L{_debug} function.
1055 For debug purpouse only. Must be first in options list. If get I{name}
1056 then call only this methods ("_test_name") if exists.
1057 Right tests will be only into source distribution. In copy files
1058 (for example distributed with --dist) number tests will be fail.
1059
1060 <g>Common options:</g>
1061 <g>---------------</g>
1062
1063 This options may be used for all command.
1064
1065 <y>-vLEVEL</y>
1066 Set verbosity level (0 - no verbosity) 0 ... 4.
1067 Default assign 3.
1068
1069 <c>-1</c> - No output. Only log file.
1070 <c>0</c> - Only global errors.
1071 <c>1</c> - Very small output, only about success and errors.
1072 <c>2</c> - As 1 and conflicts.
1073 <c>3</c> - Normal output. As 2 and warnings.
1074 <c>4</c> - Large output. As 3 and file operation.
1075 <c>5</c> - Huge output. As 4 and logging.
1076
1077 <y>-lFLAG</y>
1078
1079 Enable <c>1</c> or disable <c>0</c> logging. FLAG may be 0 or 1.
1080 Default assign 1.
1081
1082 <y>-tFLAG</y>
1083
1084 Enable <c>1</c> or disable <c>0</c> debug output. FLAG may be 0 or 1.
1085 Default assign 0.
1086
1087 <y>-mFLAG</y>
1088
1089 Enable <c>1</c> or disable <c>0</c> emulation. FLAG may be 0 or 1.
1090 Do not realy perform write operation. Do all actions as
1091 real command but do not change any files.
1092 Default assign 0.
1093 Usually this option use with "-l" or "-t" options for logging
1094 emulation result.
1095
1096 <y>-cFLAG</y>
1097
1098 Enable <c>1</c> or disable <c>0</c> colorize output. FLAG may be 0 or 1.
1099 Default assign 1.
1100
1101
1102
1103
1104 IF YOU LIKE PYBAG AND FOUND IT USEFUL WHEN YOU CAN DONATE TO AUTHOR
1105 SOME MONEY ON PROJECT PAGE: http://pybag.sourceforge.net.
1106
1107
1108 If you do not want donate money then you can treat the
1109 author cap of coffee and pizza.
1110
1111 THANK YOU.
1112
1113 """
1114
1115
1116
1117
1118
1119 _tips = [
1120 u'All you changes and preferences will be saved only if "Emulation mode" turn off.',
1121 u'You can hide/show columns in list in menu when click right mouse button on the columns header.',
1122 u'If you use any root only for backup then you can mark it in preferences as "Backup" and ' \
1123 u'synchronization will be up 2 times faster.',
1124 u'In preferences you can adjust default filters for items list.',
1125 u'If you click right mouse button on column header then you can move column "To left" or "To right".',
1126 u'If you like PYBAG and fount it useful when you can donate to author some money at project ' \
1127 u'page: http://pybag.sourceforge.net. If you do not want donate money then you can treat the author ' \
1128 u'cap of coffee and pizza. Thank you.',
1129 u'In backup roots files in backuped copy must not be changed, but if its changed you can do full synchronization ' \
1130 u'by check "Backup mode synchronize".',
1131 u'Backup roots synchronize up 2 times faster then usual but this is only one way synchronization useful for backup purpose.' \
1132 u' This mean that changes in backuped copy will not be tracked.',
1133 u'You can turn on in preferences ability to save columns positions at program exit.',
1134 u'In filter field you can use not only wilds character (* and ?), you can use regular expression. Regular expression must ' \
1135 u'start from exlamination "!".',
1136 u'For huge synchronization you can use command line interface. CLI is few faster then GUI.',
1137 u'If you use CLI and options "-t0 -l0 -v2 -gx -py" then synchronization will be fast (no debug, no logging, no report' \
1138 u' auto answer yes for continue, low verbosity).',
1139 u'If you have problem with daylight saving (synchronization between Windows and FAT - after changes daylight all files marked' \
1140 u' as changed) you can use "Action->Timeshift->Timeshift to ..." to change modification date in files, without realy copying.',
1141 ]
1142