Provided by: task_2.0.0.release-0ubuntu2_i386 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>