task-sync(5)							   User Manuals 						      task-sync(5)

NAME

       task-sync - A tutorial for the task(1) data synchronization capabilities.

DESCRIPTION

       Taskwarrior  has  built-in support for synchronization, which can be used to keep two task databases up to date, regardless of which one is
       used.  This capability can also be used to keep a backup copy of your task database on another machine.

       Taskwarrior can use various protocols for transferring the data.

HOW IT WORKS

       If you were to manually attempt to keep two separate task databases up to date, you would  need	to  inspect  both  databases,  and  detect
       changes	that  occurred	in  each  one.	 Those	changes would need to be migrated to the other database, while being careful not to miss a
       change, and not to confuse an 'add' in one with a 'delete' in the other.

       The synchronization feature does just this.  It can transfer task databases, compare tasks, and apply changes where necessary.

NEW COMMANDS

       Taskwarrior has 'pull', 'push' and 'merge' commands which perform the steps necessary to move files around and combine them.  In the common
       use  case, you would only need to use the 'merge' command.  These commands take an argument that is a URI, which indicates where the remote
       database resides.

       To be clear, the local database always refers to your ~/.task directory (unless overridden), and the remote database is always specified by
       URI.

MERGE

       The merge command will fetch task data via URI and combine it with the local task database.  The syntax is:

	      task merge [<URI>]

       The  URI  is  optional  if the merge.default.uri configuration variable is set.	The URI may point to a different directory, or it may be a
       different computer.  Here is an example of the merge command:

	      $ task merge ~/work/

       This URI (~/work/) is a path name, which means the remote database is on the same computer.  Taskwarrior will fetch the data from the  URI,
       and merge it with your local data in ~/.task.

       When  complete,	you will be asked whether you would like to push the combined data back to the remote location specified by the URI.  This
       is useful if you are keeping two task databases synchronized, but it can be turned off.	See CONFIGURATION.

       Note that a merge operation is not atomically reversible.  You could however run the 'task undo' command repeatedly to undo the effects.

PUSH

       The push command will copy the local task database to the specified URI.  The syntax is:

	      task push [<URI>]

       The URI is optional if the push.default.uri configuration variable is set.  This command is useful for making backup copies  of	your  task
       database.

       Note  that the task files at the location specified by the URI are simply overwritten, so don't expect any merging to occur.  Misused, push
       can be dangerous.

PULL

       The pull command will copy a task database from a URI to the local task database (~/.task by default).  The syntax is:

	      task pull [<URI>]

       The URI is optional if the pull.default.uri configuration variable is set.  This command is useful for restoring a backup copy of your task
       database.

       Note  that your local task database files will be simply overwritten by the files obtained from the location specified by the URI, so don't
       expect any merging to occur.  Misused, pull can be dangerous.

URI TYPES

       The most basic URI is a path name on the local machine.	An example would be:

	      /home/bob/.task/

       All the other URIs allow access to remote machines.  The first uses SSH and scp (either form can be used):

	      ssh://[user@]host[:port]/absolute/path/to/.task/
	      [user@]host:/absolute/path/to/.task/

       In both cases paths are considered to be absolute. You can specify paths relative to the users home directory as follows:

	      ssh://[user@]host[:port]/.task/
	      [user@]host:.task/

       or even shorter

	      [user@]host:.task/

       Remark: Since taskwarrior simply calls the scp binary you can specify very much anything that scp would accept,	e.g.  host  configurations
       from ~/.ssh/config or ~username expansion:

	      ssh://configured-host/~[username]/.task/
	      configured-host:~[username]/.task/

       Rsync is another supported protocol that minimizes network traffic, by a clever algorithm that doesn't copy files that have not changed:

	      rsync://[user@]host.xz[:port]/path/to/.task/

       Curl supports several protocols that can transfer data using HTTP, HTTPS and FTP:

	      http://host[:port]/path/to/.task/
	      https://host[:port]/path/to/.task/
	      ftp://[user@]host[:port]/path/to/.task/

       You can use single quotes to encapsulate user names that contain delimiting characters like '@', '/' or ':', e.g.:

	      ssh://'user@name'@host/

       Remember to escape the quotes on your shell:

	      $ task push ftp://'user@name':host/

CONFLICTS

       When  modifications on the local and remote machine conflict, for example if both machines change the project name of the same task to dif-
       ferent values, then Taskwarrior automatically selects the most recent change.  Thus, there are no conflicts.

EXAMPLE - Backup on another machine
       One very good use of 'push' is to make backup copies of your task database in another location.	Suppose your task database is kept in  the
       usual place, in the ~/.task directory, and you wanted to make a backup copy in ~/backup.  You would use this command:

	      $ task push ~/backup/

       This  would  copy  the  files in ~/.task to ~/backup, overwriting the files that were already in ~/backup.  To backup your files to another
       machine, you could use:

	      $ task push user@host:backup

       This could be improved by setting the push.default.uri configuration variable and then relying on the default, like this:

	      $ task config push.default.uri user@host:backup

       and then you need only run the push command:

	      $ task push

       and the default push URI will be used.  If you wanted to restore a backup, you simply use the pull command instead:

	      $ task pull user@host:backup

       This can be simplified by setting the pull.default.uri configuration variable and then relying on the default, like this:

	      $ task config pull.default.uri user@host:backup

       Note that pull and push will blindly overwrite the task files without any merging.  Be careful.

EXAMPLE - Keeping two task databases synchronized
       The most common synchronization will be to keep two task databases synchronized on different machines.  Here is a full  example,  including
       setup that illustrates this.

       Suppose	there  are  two  machines,  named 'local' and 'remote', for simplicity.  Taskwarrior is installed on both machines.  The different
       machines are indicated here by the prompt.  Suppose Alice enters two tasks on her local machine:

	      local> task add Deliver the new budget proposal due:tuesday
	      local> task add Set up a meeting with Bob

       Then later adds a task on the remote machine:

	      remote> task add Present the budget proposal at the big meeting due:thursday

       Now on the local machine, Alice merges the two task databases:

	      local> task merge alice@remote:.task
	      Would you like to push the changes to 'alice@remote:.task'?  Y

       Taskwarrior has combined the two task databases on local, then pushed the changes back to remote.  Now suppose Alice changes the  due  date
       for task 1 on remote:

	      remote> task 1 due:wednesday

       Now on the local machine, Alice sets up a default URI and autopush:

	      local> task config merge.default.uri alice@remote:.task
	      local> task config merge.autopush yes

       Now Alice can simply run merge to make sure that the new due date is copied to the local machine:

	      local> task merge

       This  time the URI is determined automatically, and after the merge the files are pushed back to the remote machine.  In a similar way, the
       remote machine can also be configured to merge from the local machine and push back to it.  Then it is just a matter of	Alice  remembering
       to merge now and then, from either machine, to have her data in two (or even more) places.

CONFIGURATION

       By  setting  these  configuration  variables,  it is possible to simplify the synchronization commands, by relying on the defaults or alias
       names.

       merge.autopush=yes|no|ask
	      This controls whether the automatic push after a merge is performed, not performed, or whether the user is asked	every  time.   The
	      default value is 'ask'.

       merge.default.uri=<uri>
	      Sets a default URI so that just the 'task merge' command be run without the need to retype the URI every time. You can also use this
	      configuration scheme to set alias names, e.g. set merge.desktop.uri and run 'task merge desktop'.

       push.default.uri=<uri>
	      Sets a default URI so that just the 'task push' command be run without the need to retype the URI every time. You can also use  this
	      configuration scheme to set alias names, e.g. set push.desktop.uri and run 'task push desktop'.

       pull.default.uri=<uri>
	      Sets  a default URI so that just the 'task pull' command be run without the need to retype the URI every time. You can also use this
	      configuration scheme to set alias names, e.g. set pull.desktop.uri and run 'task pull desktop'.

       Note that, when using SSH/scp, hostnames will be expanded due to the ssh configuration file ~/.ssh/config.

EXTERNAL DEPENDENCIES

       Depending on the URI protocols used, the utilities 'scp', 'rsync' and 'curl' must be installed and accessible  via  the	$PATH  environment
       variable.

       If  you	have  deleted  your  ~/.task/undo.data	file  to  save	space, you will be unable to merge.  The change transactions stored in the
       undo.data file are used for synchronization.

CREDITS &; COPYRIGHTS
       Copyright (C) 2006 - 2012 P. Beckingham, F. Hernandez.

       The sync capabilities were written by J. Schlatow.  Parts copyright (C) 2010 - 2012 J. Schlatow.

       Taskwarrior is distributed under the MIT license. See http://www.opensource.org/licenses/mit-license.php for more information.

SEE ALSO

       task(1), taskrc(5), task-faq(5), task-color(5), task-tutorial(5), ssh_config(5)

       For more information regarding task, the following may be referenced:

       The official site at
	      <http://taskwarrior.org>

       The official code repository at
	      <git://tasktools.org/task.git/>

       You can contact the project by writing an email to
	      <support@taskwarrior.org>

REPORTING BUGS

       Bugs in task may be reported to the issue-tracker at
	      <http://taskwarrior.org>

task 2.0.0							    2012-03-17							      task-sync(5)