Provided by: task_2.0.0.release-0ubuntu2_amd64 bug

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  different  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>