annotate silvermirror-whitepaper.txt @ 46:b19b605b5b29

add example ini
author Jeff Hammel <k0scist@gmail.com>
date Fri, 13 Aug 2021 14:55:38 -0700
parents 5f95af14b51c
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
1 = SilverMirror Whitepaper =
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
2
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
3 It is necessary to maintain parallel directory structures of various
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
4 resources across an arbitrary number of computers. The traditional
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
5 approach is the central server model, where files live in one
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
6 canonical location and the network is used to give access to the data.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
7 However, this model has deficiencies, chiefly among them that if the
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
8 server goes down or must be moved a considerable amount of effort must
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
9 be extended to set up a new central server.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
10
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
11 Distributed version control, often of nominal use (in the case where a
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
12 canonical trunk exists) is ideally suited to provide mirroring of
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
13 desired resources across computers.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
14
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
15 == Implementation ==
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
16
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
17 A front end to a DVCS or other - unison is completed,
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
18 mercurial is up next -
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
19 will be written to keep resources in sync across an arbitrary number
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
20 of computers. The front end, called SilverMirror, may be used to push
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
21 or pull changes to resources. Optionally, a daemon will monitor
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
22 changes to resources and push or pull changes at desired intervals.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
23
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
24 The use should be as natural as possible and require no interaction
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
25 for everday tasks. A resource consists of a directory and all
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
26 subdirectories and their contents. Once a resource is denoted as
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
27 versioned, any change to the resource's directory structure should be
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
28 mirrored across machines without user intervention. Files matching a
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
29 pattern may be ignored, either globally or on a per resource basis,
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
30 for the purpose of versioning.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
31
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
32 == Configuration ==
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
33
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
34 SilverMirror is configured via an INI file containing a section for
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
35 each resource and a section for application configuration.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
36
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
37 The main section, denoted [::SilverMirror::], has the following options:
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
38
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
39 * directory: base directory for SilverMirror. The SilverMirror
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
40 configuration is stored in ${directory}/.silvermirror . If omitted,
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
41 the user's home directory is used.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
42
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
43 * ignore: global patterns of files and directories to ignore. Paths
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
44 matching these patterns will not be versioned.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
45
1
9b139702a8f9 use a real backend architecture with an inteface and vastly simplify unify.py
k0s <k0scist@gmail.com>
parents: 0
diff changeset
46 * reflector: which back-end to use (unison, hg, etc)
9b139702a8f9 use a real backend architecture with an inteface and vastly simplify unify.py
k0s <k0scist@gmail.com>
parents: 0
diff changeset
47
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
48 Each section has the following configuration options:
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
49
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
50 * directory: path of the resource. If a relative path is used, it is
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
51 joined with the directory setting from the main section. If this
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
52 setting is not specified, the section name is used as a relative path.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
53
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
54 * ignore: paths not to version on a per resource basis. This is in
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
55 addition to the patterns specified by the ignore setting in the main
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
56 section.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
57
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
58 * conflict: handler to resolve conflict.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
59
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
60 * hosts: hosts to push/pull from
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
61
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
62 In order to ensure coherency among resources, all relevant
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
63 configuration options must be synced prior to push/pull transactions.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
64
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
65 Default Configuration::
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
66
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
67 [::SilverMirror::]
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
68 conflict = ClobberRemote
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
69
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
70 Example of a more complex configuration::
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
71
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
72 [::SilverMirror::]
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
73 conflict.push = ClobberRemote
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
74 conflict.pull = ClobberLocal
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
75
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
76 == Push ==
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
77
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
78 Push changes to remote resources. When resources are pushed, first
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
79 changes are pulled from each remote host in turn, conflicts between
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
80 local and remote changes are resolved (see Behavior on Conflicts),
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
81 then local modifications are pushed. This is done to keep the
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
82 resources in sync.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
83
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
84 When new files are added to the resource they are automatically added
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
85 to the hg repository. When resource files are edited the changes are
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
86 pushed to the repository. When a conflict occurs between local
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
87 resources and remote resources, the conflict handler is used.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
88
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
89 == Pull ==
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
90
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
91 Get changes to the cloud filesystem resources. If no host is
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
92 specified, pull changes from all known + accessible hosts.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
93
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
94 == Namespaced Resources ==
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
95
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
96 It is possible to maintain versioning of a subdirectory within a
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
97 resource.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
98
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
99 Example::
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
100
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
101 [docs]
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
102 directory = /path/to/docs
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
103
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
104 [docs:private]
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
105
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
106 This configuration snippet describes a resource, [docs:private],
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
107 namespaced within the [docs] resource. [docs:private] inherits
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
108 configuration and behavior from [docs] but may be dealt with
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
109 separately. For example, some computers in the cloud may not have
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
110 [docs:private] specified in their configuration and so will not get a
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
111 copy of it upon pulling. A common use case is specifying a
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
112 subdirectory to be omitted with the ignore option in the configuration
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
113 file, then, when this subdirectory needs to be shared between multiple
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
114 computers, removing it from the ignore values and including as a
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
115 namespaced resource.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
116
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
117 In the above example, because the directory option was not specified
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
118 in the [docs:private] section, the path to [docs:private] is taken
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
119 from its namespace (private) and the directory of its parent resource.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
120 So its base directory is /path/to/docs/private . If a relative path
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
121 was specified in the directory option of the [docs:private] section,
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
122 it would be joined with the base directory of [docs].
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
123
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
124 == Behavior on Conflicts ==
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
125
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
126 Conflict handlers are set via setuptools entry points. Several
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
127 conflict handlers are provided with SilverMirror:
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
128
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
129 * ClobberLocal: replace local changes with changes from remote files
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
130
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
131 * ClobberRemote: replace remote file changes with changes from local
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
132 files
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
133
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
134 * Edit: invoke an editor (default: $EDITOR) to interactively resolve
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
135 the conflicts
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
136
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
137 The conflict handler may also be specified from the command line:
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
138
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
139 silvermirror push -d ClobberRemote
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
140
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
141 == Command Line Usage ==
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
142
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
143 silvermirror [push|pull] [resource] [options]
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
144
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
145 In the simplest invocation, SilverMirror is used with no command line
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
146 arguments::
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
147
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
148 silvermirror
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
149
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
150 This pushes changes of the resource as determined by the current
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
151 working directory after pulling outstanding changes from all
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
152 applicable remote computers and invoking the conflict handler for
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
153 push. If the current working directory is not within a resource, all
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
154 resources will be pushed.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
155
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
156 Finer control is obtained by specifying command line arguments:
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
157
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
158 [push|pull] : whether to use the push method (which includes pulling
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
159 for changes; see above) or the pull method. If not specified, the
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
160 resource is pushed.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
161
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
162 [resource] : which resource to act upon. This can be the resource
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
163 name, as specified in the .ini file, or the path to the base directory
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
164 of the resource. Note that if a path is specified, it must be to the
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
165 base directory of the resource as SilverMirror has no notion of
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
166 disparate versioning within a resource. If the resource is not
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
167 specified, the resource that the current working directory is within
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
168 is used. If the current working directory is not in a resource path,
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
169 all resources are acted upon in turn. If the key word "--all" is used,
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
170 all resources will also be acted upon.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
171
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
172 [options] : several command line switches are available to the
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
173 silvermirror program:
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
174
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
175 * -d <handler> : specify which conflict handler to use. <handler>
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
176 should be the name of the desired conflict handler. A list of all
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
177 conflict handlers is available with the "--conflict-handlers" option.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
178
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
179 * -H <host>, --host=<host> : pull and/or push only to specified
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
180 hosts. If this option is used more than once, the hosts specified will
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
181 be acted upon.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
182
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
183 * --conflict-handlers : list the name and description (if
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
184 specified) for all available conflict handlers.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
185
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
186 * --help : displays help and usage information
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
187
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
188 Behavior Respecting Versioned Directories
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
189
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
190 SilverMirror does not desire to duplicate versioning on directories
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
191 already under version control (svn, bzr, hg). These resources are
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
192 automatically ignore. In a future implementation, these resources
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
193 would optionally be checked out or updated upon a pull.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
194
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
195 == Automatic Syncronization ==
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
196
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
197 SilverMirror includes a script that will automatically invoke
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
198 syncronizing the resources in a specified period of time. This daemon,
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
199 called silvermirrord, is invoked from the command line with options
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
200 parallel to the silvermirror program. One additional option, -s, tells
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
201 how many seconds between syncs. Upon invocation, this program puts
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
202 itself in the background and performs the desired sync every number of
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
203 seconds specified. It is important that the conflict handler specified
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
204 is noninteractive, otherwise the daemon will hang forever.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
205
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
206 As an alternative, the silvermirror program may be invoked from a cron
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
207 job.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
208
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
209 == Events ==
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
210
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
211 SilverMirror [TODO] may be hooked up to an event listener for
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
212 filesystem changes and sync on them.
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
213
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
214 == Future Work ==
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
215
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
216 SilverMirror implements a cloud filesystem which may be accessed
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
217 nearly transparently by an arbitrary number of computers. Several
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
218 improvements could extend SilverMirror to solve several deficiencies
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
219 of modern filesystem.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
220
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
221 * tagging: in most filesystems, a file has a canonical location.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
222 However, it may be desirable to have the file accesible via multiple
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
223 paths. In practice, this is achieved via symbolic links. However, this
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
224 requires manual maintaince of links vs the canonical location. Noting
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
225 that this problem is identical to tagging, a solution minimizing
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
226 manual intervention could be added to SilverMirror.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
227
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
228 * update of web documents: modern computers deal heavily with
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
229 documents via URLs. It is noted that this includes files, the URL of a
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
230 file with path ${PATH} being file://${PATH} noted implicitly from
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
231 contexts. However, existing shells and operating systems have no
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
232 mechanism for indicating that a "file" is a web resource. Such
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
233 functionality could be added to SilverMirror so that up-to-date
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
234 versions of web resources could be maintained. This infrastructure
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
235 could also include notions for updating versioned resources (see
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
236 Behavior Respecting Versioned Directories) with parallel notation.
7
d3d0b9414e19 add idea for portable silvermirror
k0s <k0scist@gmail.com>
parents: 1
diff changeset
237
d3d0b9414e19 add idea for portable silvermirror
k0s <k0scist@gmail.com>
parents: 1
diff changeset
238 * portable SilverMirror: a utility should be created to put a
d3d0b9414e19 add idea for portable silvermirror
k0s <k0scist@gmail.com>
parents: 1
diff changeset
239 SilverMirror backup scheme on portable media. This not only
d3d0b9414e19 add idea for portable silvermirror
k0s <k0scist@gmail.com>
parents: 1
diff changeset
240 includes a backup of the files, but also the SilverMirror program and
d3d0b9414e19 add idea for portable silvermirror
k0s <k0scist@gmail.com>
parents: 1
diff changeset
241 all of the files necessary to create a new SilverMirror node.
13
584a847d2491 note on FF sync
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
242
584a847d2491 note on FF sync
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
243 * SilverMirror + Firefox Sync
14
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
244
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
245 == Vision ==
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
246
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
247 Essentially, SilverMirror is intended as a portable filesystem on a
Jeff Hammel <jhammel@mozilla.com>
parents: 13
diff changeset
248 filesystem type interface.