Mercurial > hg > silvermirror

annotate silvermirror-whitepaper.txt @ 1:9b139702a8f9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
use a real backend architecture with an inteface and vastly simplify unify.py
author k0s <k0scist@gmail.com>
date Sat, 26 Sep 2009 23:36:42 -0400
parents abb358e2434c
children d3d0b9414e19
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
1 SilverMirror Whitepaper
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
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
15 Implementation
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
16
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
17 A front end to a DVCS - most likely mercurial but potentially bzr -
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
18 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
19 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
20 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
21 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
22
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
23 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
24 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
25 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
26 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
27 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
28 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
29 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
30
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
31 Configuration
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
32
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
33 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
34 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
35
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
36 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
37
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
38 * 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
39 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
40 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
41
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
42 * 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
43 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
44
1
9b139702a8f9 use a real backend architecture with an inteface and vastly simplify unify.py
k0s <k0scist@gmail.com>
parents: 0
diff changeset
45 * 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
46
0
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
47 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
48
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
49 * 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
50 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
51 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
52
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
53 * 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
54 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
55 section.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
56
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
57 * 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
58
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
59 * 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
60
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
61 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
62 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
63
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
64 Default Configuration:
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
65
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
66 [::SilverMirror::]
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
67 conflict = ClobberRemote
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
68
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
69 Example of a more complex configuration:
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
70
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
71 [::SilverMirror::]
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
72 conflict.push = ClobberRemote
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
73 conflict.pull = ClobberLocal
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
74
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
75 Push
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
76
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
77 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
78 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
79 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
80 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
81 resources in sync.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
82
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
83 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
84 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
85 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
86 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
87
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
88 Pull
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
89
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
90 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
91 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
92
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
93 Namespaced Resources
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
94
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
95 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
96 resource.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
97
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
98 Example:
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
99
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
100 [docs]
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
101 directory = /path/to/docs
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
102
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
103 [docs:private]
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
104
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
105 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
106 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
107 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
108 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
109 [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
110 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
111 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
112 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
113 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
114 namespaced resource.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
115
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
116 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
117 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
118 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
119 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
120 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
121 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
122
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
123 Behavior on Conflicts
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
124
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
125 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
126 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
127
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
128 * 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
129
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
130 * 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
131 files
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
132
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
133 * 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
134 the conflicts
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
135
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
136 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
137
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
138 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
139
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
140 Command Line Usage
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
141
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
142 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
143
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
144 In the simplest invocation, SilverMirror is used with no command line
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
145 arguments:
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
146
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
147 silvermirror
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
148
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
149 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
150 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
151 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
152 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
153 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
154
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
155 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
156
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
157 [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
158 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
159 resource is pushed.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
160
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
161 [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
162 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
163 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
164 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
165 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
166 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
167 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
168 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
169 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
170
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
171 [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
172 silvermirror program:
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
173
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
174 * -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
175 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
176 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
177
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
178 * -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
179 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
180 be acted upon.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
181
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
182 * --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
183 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
184
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
185 * --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
186
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
187 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
188
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
189 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
190 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
191 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
192 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
193
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
194 Automatic Syncronization
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
195
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
196 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
197 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
198 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
199 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
200 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
201 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
202 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
203 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
204
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
205 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
206 job.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
207
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
208 Future Work
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
209
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
210 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
211 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
212 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
213 of modern filesystem.
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
214
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
215 * 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
216 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
217 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
218 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
219 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
220 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
221
abb358e2434c initial commit of silvermirror, from http://my-svn.assembla.com/svn/arbez/silvermirror
k0s <k0scist@gmail.com>
parents:
diff changeset
222 * 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
223 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
224 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
225 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
226 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
227 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
228 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
229 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
230 Behavior Respecting Versioned Directories) with parallel notation.