-
-
Notifications
You must be signed in to change notification settings - Fork 271
/
task-sync.5.in
231 lines (157 loc) · 7.15 KB
/
task-sync.5.in
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
.TH task-sync 5 2016-02-24 "${PACKAGE_STRING}" "User Manuals"
.SH NAME
task-sync \- A discussion and tutorial for the various
.BR task (1)
data synchronization capabilities.
.SH INTRODUCTION
Taskwarrior can synchronize your tasks to a server. This has a few benefits:
.br
- Makes your tasks accessible from multiple systems, called "replicas".
.br
- Provides a backup of your tasks.
.br
- Saves disk space.
For example, you might want a replica of your tasks on your laptop and on your phone.
NOTE: A side-effect of synchronization is that once changes have been
synchronized, they cannot be undone. This means that each time synchronization
is run, it is no longer possible to undo previous operations.
.SH MANAGING SYNCHRONIZATION
.SS Adding a Replica
To add a new replica, configure a new, empty replica identically to
the existing replica, and run `task sync`.
.SS When to Synchronize
Taskwarrior can perform a sync operation at every garbage collection (gc) run.
This is the default, and is appropriate for local synchronization.
For synchronization to a server, a better solution is to run
$ task sync
periodically, such as via
.BR cron (8) .
.SH CONFIGURATION
Taskwarrior provides several options for synchronizing your tasks:
- To a server specifically designed to handle Taskwarrior data.
+ To a cloud storage provider. Currently only GCP is supported.
- To a local, on-disk file.
For most of these, you will need an encryption secret used to encrypt and
decrypt your tasks. This can be any secret string, and must match for all
replicas sharing tasks.
$ task config sync.encryption_secret <encryption_secret>
Tools such as
.BR pwgen (1)
can generate suitable secret values.
.SS Sync Server
To synchronize your tasks to a sync server, you will need the following
information from the server administrator:
.br
- The server's URL ("origin", such as "https://tw.example.com")
.br
- A client ID ("client_id") identifying your tasks
Configure Taskwarrior with these details:
$ task config sync.server.origin <origin>
$ task config sync.server.client_id <client_id>
Note that the origin must include the scheme, such as 'http://' or 'https://'.
.SS Google Cloud Platform
To synchronize your tasks to GCP, use the GCP Console to create a new project,
and within that project a new Cloud Storage bucket. The default settings for
the bucket are adequate.
Authenticate to the project with:
$ gcloud config set project $PROJECT_NAME
$ gcloud auth application-default login
Then configure Taskwarrior with:
$ task config sync.gcp.bucket <bucket-name>
However you can bring your own service account credentials if your
`application-default` is already being used by some other application
To begin, navigate to the "IAM and Admin" section in the Navigation Menu, then select "Roles."
On the top menu bar within the "Roles" section, click "CREATE ROLE."
Provide an appropriate name and description for the new role.
Add permissions to your new role using the filter "Service:storage" (not the "Filter permissions by role" input box).
Select the following permissions:
- storage.buckets.create
- storage.buckets.get
- storage.buckets.update
- storage.objects.create
- storage.objects.get
- storage.objects.list
- storage.objects.update
- storage.objects.delete
Create your new role.
On the left sidebar, navigate to "Service accounts."
On the top menu bar within the "Service accounts" section, click "CREATE SERVICE ACCOUNT."
Provide an appropriate name and description for the new service account.
Select the role you just created and complete the service account creation process.
Now, in the Service Account dashboard, click into the new service account and select "keys" on the top menu bar.
Click on "ADD KEY" to create and download a new key (a JSON key).
Then configure Taskwarrior with:
$ task config sync.gcp.bucket <bucket-name>
$ task config sync.gcp.credential_path <absolute-path-to-downloaded-credentials>
.SS Local Synchronization
In order to take advantage of synchronization's side effect of saving disk
space without setting up a remote server, it is possible to sync tasks locally.
To configure local sync:
$ task config sync.local.server_dir /path/to/sync
The default configuration is to sync to a database in the task directory
("data.location").
.SH RUNNING TASKCHAMPION-SYNC-SERVER
The TaskChampion sync server is an HTTP server supporting multiple users.
Users are identified by a client ID, and users with different client IDs are
entirely independent. Task data is encrypted by Taskwarrior, and the sync
server never sees un-encrypted data.
The server is developed in
https://github.com/GothenburgBitFactory/taskchampion-sync-server.
.SS Adding a New User
To add a new user to the server, invent a new client ID with a tool like
`uuidgen` or an online UUID generator. There is no need to configure the server
for this new client ID: the sync server will automatically create a new user
whenever presented with a new client ID. Supply the ID, along with the
origin, to the user for inclusion in their Taskwarrior config. The user should
invent their own "encryption_secret".
.SH AVOIDING DUPLICATE RECURRING TASKS
If you run multiple clients that sync to the same server, you will need to run
this command on your primary client (the one you use most often):
$ task config recurrence on
And on the other clients, run:
$ task config recurrence off
This protects you against the effects of a sync/duplication bug.
.SH ALTERNATIVE: FILE SHARING SERVICES
There are many file sharing services, such as DropBox, Amazon S3, Google Drive,
SkyDrive and more. This technique involves storing your .task directory in a
shared directory under the control of the file hosting services.
Syncing happens quickly, although it is possible to run into conflict situations
when there is no network connectivity, and the tasks are modified in two
separate locations. This is because the file hosting service knows only about
files, and it has no idea how to merge tasks. Avoid this problem by never
modifying the same task on two machines, without an intervening sync.
Setup simply involves creating the directory and modifying your data.location
configuration variable like this:
$ task config data.location /path/to/shared/directory
Strengths:
.br
- Good client support
.br
- Easy setup
.br
- Transparent use
Weaknesses:
.br
- Tasks are not properly merged
.SH "CREDITS & COPYRIGHTS"
Copyright (C) 2006 \- 2021 T. Babej, P. Beckingham, F. Hernandez.
Taskwarrior is distributed under the MIT license. See
https://www.opensource.org/licenses/mit-license.php for more information.
.SH SEE ALSO
.BR task(1),
.BR taskrc(5),
.BR task-color(5),
For more information regarding Taskwarrior, see the following:
.TP
The official site at
<https://taskwarrior.org>
.TP
The official code repository at
<https://github.com/GothenburgBitFactory/taskwarrior>
.TP
You can contact the project by emailing
<support@GothenburgBitFactory.org>
.SH REPORTING BUGS
.TP
Bugs in Taskwarrior may be reported to the issue-tracker at
<https://github.com/GothenburgBitFactory/taskwarrior/issues>