1task-sync(5) User Manuals task-sync(5)
2
6 task-sync - A tutorial for the task(1) data synchronization capabili‐
7 ties.
8
11 Taskwarrior has built-in support for synchronization, which can be used
12 to keep two task databases up to date, regardless of which one is used.
13 This capability can also be used to keep a backup copy of your task
14 database on another machine.
15 Taskwarrior can use various protocols for transferring the data.
17
20 If you were to manually attempt to keep two separate task databases up
21 to date, you would need to inspect both databases, and detect changes
22 that occurred in each one. Those changes would need to be migrated to
23 the other database, while being careful not to miss a change, and not
24 to confuse an 'add' in one with a 'delete' in the other.
25 The synchronization feature does just this. It can transfer task data‐
27 bases, compare tasks, and apply changes where necessary.
28
31 Taskwarrior has 'pull', 'push' and 'merge' commands which perform the
32 steps necessary to move files around and combine them. In the common
33 use case, you would only need to use the 'merge' command. These com‐
34 mands take an argument that is a URI, which indicates where the remote
35 database resides.
36 To be clear, the local database always refers to your ~/.task directory
38 (unless overridden), and the remote database is always specified by
39 URI.
40
43 The merge command will fetch task data via URI and combine it with the
44 local task database. The syntax is:
45 task merge [<URI>]
47 The URI is optional if the merge.default.uri configuration variable is
49 set. The URI may point to a different directory, or it may be a dif‐
50 ferent computer. Here is an example of the merge command:
51 $ task merge ~/work/
53 This URI (~/work/) is a path name, which means the remote database is
55 on the same computer. Taskwarrior will fetch the data from the URI,
56 and merge it with your local data in ~/.task.
57 When complete, you will be asked whether you would like to push the
59 combined data back to the remote location specified by the URI. This
60 is useful if you are keeping two task databases synchronized, but it
61 can be turned off. See CONFIGURATION.
62 Note that a merge operation is not atomically reversible. You could
64 however run the 'task undo' command repeatedly to undo the effects.
65
68 The push command will copy the local task database to the specified
69 URI. The syntax is:
70 task push [<URI>]
72 The URI is optional if the push.default.uri configuration variable is
74 set. This command is useful for making backup copies of your task
75 database.
76 Note that the task files at the location specified by the URI are sim‐
78 ply overwritten, so don't expect any merging to occur. Misused, push
79 can be dangerous.
80
83 The pull command will copy a task database from a URI to the local task
84 database (~/.task by default). The syntax is:
85 task pull [<URI>]
87 The URI is optional if the pull.default.uri configuration variable is
89 set. This command is useful for restoring a backup copy of your task
90 database.
91 Note that your local task database files will be simply overwritten by
93 the files obtained from the location specified by the URI, so don't
94 expect any merging to occur. Misused, pull can be dangerous.
95
98 The most basic URI is a path name on the local machine. An example
99 would be:
100 /home/bob/.task/
102 All the other URIs allow access to remote machines. The first uses SSH
104 and scp (either form can be used):
105 ssh://[user@]host[:port]/path/to/undo.data
107 [user@]host:/path/
108 Rsync is another supported protocol that minimizes network traffic, by
110 a clever algorithm that doesn't copy files that have not changed:
111 rsync://[user@]host.xz[:port]/path/to/undo.data
113 Curl supports several protocols that can transfer data using HTTP,
115 HTTPS and FTP:
116 http://host[:port]/path/to/undo.data
118 https://host[:port]/path/to/undo.data
119 ftp://[user@]host[:port]/path/to/undo.data
120 You can use single quotes to encapsulate user names that contain delim‐
122 iting characters like '@', '/' or ':', e.g.:
123 ssh://'user@name'@host/
125 Remember to escape the quotes on your shell:
127 $ task push ftp://´user@name´:host/
129
132 When modifications on the local and remote machine conflict, for exam‐
133 ple if both machines change the project name of the same task to dif‐
134 ferent values, then Taskwarrior automatically selects the most recent
135 change. Thus, there are no conflicts.
136
139 One very good use of 'push' is to make backup copies of your task data‐
140 base in another location. Suppose your task database is kept in the
141 usual place, in the ~/.task directory, and you wanted to make a backup
142 copy in ~/backup. You would use this command:
143 $ task push ~/backup/
145 This would copy the files in ~/.task to ~/backup, overwriting the files
147 that were already in ~/backup. To backup your files to another
148 machine, you could use:
149 $ task push user@host:backup
151 This could be improved by setting the push.default.uri configuration
153 variable and then relying on the default, like this:
154 $ task config push.default.uri user@host:backup
156 and then you need only run the push command:
158 $ task push
160 and the default push URI will be used. If you wanted to restore a
162 backup, you simply use the pull command instead:
163 $ task pull user@host:backup
165 This can be simplified by setting the pull.default.uri configuration
167 variable and then relying on the default, like this:
168 $ task config pull.default.uri user@host:backup
170 Note that pull and push will blindly overwrite the task files without
172 any merging. Be careful.
173
176 The most common synchronization will be to keep two task databases syn‐
177 chronized on different machines. Here is a full example, including
178 setup that illustrates this.
179 Suppose there are two machines, named 'local' and 'remote', for sim‐
181 plicity. Taskwarrior is installed on both machines. The different
182 machines are indicated here by the prompt. Suppose Alice enters two
183 tasks on her local machine:
184 local> task add Deliver the new budget proposal due:tuesday
186 local> task add Set up a meeting with Bob
187 Then later adds a task on the remote machine:
189 remote> task add Present the budget proposal at the big meeting
191 due:thursday
192 Now on the local machine, Alice merges the two task databases:
194 local> task merge alice@remote:.task
196 Would you like to push the changes to 'alice@remote:.task'? Y
197 Taskwarrior has combined the two task databases on local, then pushed
199 the changes back to remote. Now suppose Alice changes the due date for
200 task 1 on remote:
201 remote> task 1 due:wednesday
203 Now on the local machine, Alice sets up a default URI and autopush:
205 local> task config merge.default.uri alice@remote:.task
207 local> task config merge.autopush yes
208 Now Alice can simply run merge to make sure that the new due date is
210 copied to the local machine:
211 local> task merge
213 This time the URI is determined automatically, and after the merge the
215 files are pushed back to the remote machine. In a similar way, the
216 remote machine can also be configured to merge from the local machine
217 and push back to it. Then it is just a matter of Alice remembering to
218 merge now and then, from either machine, to have her data in two (or
219 even more) places.
220
223 By setting these configuration variables, it is possible to simplify
224 the synchronization commands, by relying on the defaults or alias
225 names.
226 merge.autopush=yes|no|ask
228 This controls whether the automatic push after a merge is per‐
229 formed, not performed, or whether the user is asked every time.
230 The default value is 'ask'.
231 merge.default.uri=<uri>
233 Sets a default URI so that just the 'task merge' command be run
234 without the need to retype the URI every time. You can also use
235 this configuration scheme to set alias names, e.g. set
236 merge.desktop.uri and run 'task merge desktop'.
237 push.default.uri=<uri>
239 Sets a default URI so that just the 'task push' command be run
240 without the need to retype the URI every time. You can also use
241 this configuration scheme to set alias names, e.g. set
242 push.desktop.uri and run 'task push desktop'.
243 pull.default.uri=<uri>
245 Sets a default URI so that just the 'task pull' command be run
246 without the need to retype the URI every time. You can also use
247 this configuration scheme to set alias names, e.g. set
248 pull.desktop.uri and run 'task pull desktop'.
249 Note that, when using SSH/scp, hostnames will be expanded due to the
251 ssh configuration file ~/.ssh/config.
252
255 Depending on the URI protocols used, the utilities 'scp', 'rsync' and
256 'curl' must be installed and accessible via the $PATH environment vari‐
257 able.
258 If you have deleted your ~/.task/undo.data file to save space, you will
260 be unable to merge. The change transactions stored in the undo.data
261 file are used for synchronization.
262
265 task was written by P. Beckingham <paul@beckingham.net>.
266 Copyright (C) 2006 - 2011 P. Beckingham, F. Hernandez.
267 The sync capabilities were written by J. Schlatow. Parts copyright (C)
269 2010 - 2011 J. Schlatow.
270 task is distributed under the GNU General Public License. See
272 http://www.gnu.org/licenses/gpl-2.0.txt for more information.
273
276 task(1), taskrc(5), task-faq(5), task-color(5), task-tutorial(5),
277 ssh_config(5)
278 For more information regarding task, the following may be referenced:
280 The official site at
283 <http://taskwarrior.org>
284 The official code repository at
287 <git://tasktools.org/task.git/>
288 You can contact the project by writing an email to
291 <support@taskwarrior.org>
292
295 Bugs in task may be reported to the issue-tracker at
296 <http://taskwarrior.org>
297task 1.9.4 2011-03-03 task-sync(5)