Commit c7370171820efc16dde1a1f60fe1c14c402979e6 - ellsync

More edits to README. Chris Pressey 5 years ago

1 changed file(s) with 21 addition(s) and 18 deletion(s). Raw diff Collapse all Expand all

+21

-18

README.md less more

0		ellsync
1		=======
	0	`ellsync`
	1	=========
2	2
3	3	_Version 0.2_
4	4	\| _Entry_ [@ catseye.tc](https://catseye.tc/node/ellsync)

8	8
9	9	<img align="right" src="images/ellsync-logo.png?raw=true" />
10	10
11		ellsync is an opinionated poka-yoke for rsync.
	11	`ellsync` is an opinionated poka-yoke for rsync.
12	12
13		* opinionated: it was designed for a particular use case for rsync
	13	* [opinionated][]: it was designed for a particular use case for rsync
14	14	(offline backups).
15		* poka-yoke: it exposes a restricted interface to rsync, which
	15	* [poka-yoke][]: it exposes a restricted interface to rsync, which
16	16	prevents using it in dangerous ways.
17	17
18		It also happens to provide some convenience, since the restricted
19		interface can be accessed by shorthand form, but the real purpose is
20		to increase safety. (I've been burned more than once using `rsync`
21		incorrectly.)
	18	Because the restricted interface that `ellsync` presents can be accessed
	19	by shorthand form, it also happens to provide some convenience over
	20	using `rsync` directly — but its real purpose is to increase safety.
	21	(I've been burned more than once when I've made a mistake using `rsync`.)
22	22
23	23	Quick start
24	24	-----------

32	32
33	33	### Backup router
34	34
35		ellsync's operation is based on a backup router which is a JSON file
	35	`ellsync`'s operation is based on a backup router which is a JSON file
36	36	that looks like this:
37	37
38	38	{

74	74	we will be prevented, because it is an error, because the direction of
75	75	the backup stream is always from canonical to cache.
76	76
77		Various other configurations are prevented. You may have noticed that rsync
78		is sensitive about whether a directory name ends in a slash or not. ellsync
	77	Various other configurations are prevented. You may have noticed that `rsync`
	78	is sensitive about whether a directory name ends in a slash or not. `ellsync`
79	79	detects when a trailing slash is missing and adds it. Thus
80	80
81	81	ellsync router.json syncdirs /media/user/External1/art /home/user/art/

92	92	Either the canonical or the cache (or both) may be offline storage (removable
93	93	media), therefore neither directory is assumed to exist (it might not exist
94	94	if the volume is not mounted.) If either of the directories does not exist,
95		ellsync will refuse to use this backup stream. Based on this, there is a
	95	`ellsync` will refuse to use this backup stream. Based on this, there is a
96	96	subcommand to list which streams are, at the moment, backupable:
97	97
98	98	ellsync router.json list

106	106	ellsync router.json sync art:
107	107
108	108	Also, since the contents of the canonical and the cache normally
109		have the same directory structure, ellsync allows specifying that
	109	have the same directory structure, `ellsync` allows specifying that
110	110	only a subdirectory of a stream is to be synced:
111	111
112	112	ellsync router.json sync /home/user/art/painting/ /media/user/External1/art/painting/

125	125
126	126	Sometimes you want to rename a subdirectory somewhere under the canonical of
127	127	one of the streams. It's completely fine to do this, but the next time it is synced,
128		rsync will treat it, in the cache, as the old subdirectory being deleted and
	128	`rsync` will treat it, in the cache, as the old subdirectory being deleted and
129	129	a new subdirectory being created. If there are a large number of files in the
130	130	subdirectory, this delete-and-create sync can take a long time. It's also not
131		obvious from rsync's logging output that everything being deleted is also being
	131	obvious from `rsync`'s logging output that everything being deleted is also being
132	132	created somewhere else.
133	133
134		To ease this situation, ellsync has a `rename` command that works like so:
	134	To ease this situation, `ellsync` has a `rename` command that works like so:
135	135
136	136	ellsync router.json rename art: sclupture sculpture
137	137

165	165
166	166	### 0.2
167	167
168		Every ellsync functionality has an explicit subcommand (`list` and `sync` to
	168	Every `ellsync` functionality has an explicit subcommand (`list` and `sync` to
169	169	start.)
170	170
171	171	`sync` was split into `sync` (takes a stream) and `syncdirs` (takes to and

176	176	### 0.1
177	177
178	178	Initial release.
	179
	180	[opinionated]: https://softwareengineering.stackexchange.com/questions/12182/what-does-opinionated-software-really-mean
	181	[poka-yoke]: https://en.wikipedia.org/wiki/Poka-yoke