gergely/taskwarrior-2.x
1
0
Fork 0
Code Issues Actions Packages Projects Releases 1 Wiki Activity

Documentation

Browse Source 
- Cleaned up obsolete references.
This commit is contained in:
Paul Beckingham
2013-09-11 00:35:25 -04:00
parent 64e8f34933
commit 0f416a9f01
5 changed files with 137 additions and 417 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
doc/man/task-faq.5.in
View File

@@ -72,9 +72,9 @@ reason to back up your task data files!
.TP
.B Q: Can I have two separate versions of taskwarrior installed? How?
Yes, and here is one simple way to do that. Install the older version of
taskwarrior, and then rename the 'task' binary to something like 't194' to
taskwarrior, and then rename the 'task' binary to something like 't230' to
reflect the version number. Then install the newer version, which will be
named 'task'. Now you have 't194' and 'task' both installed, both using the
named 'task'. Now you have 't230' and 'task' both installed, both using the
same configuration and data.
Note that the older version will not be aware of any new configuration settings
@@ -86,6 +86,9 @@ Note also that the man pages will overwrite, which is why it is suggested that
the older version be installed first, so that you benefit from improved
documentation.
Is this a good idea? Not really. You should be using the latest software
whenever possible, enjoying the benefits of enhancements and bug fixes.
.TP
.B Q: How do I build a Darwin 32bit version of task
The taskwarrior packages will not work on a 32-bit OSX installation on Core
@@ -159,11 +162,6 @@ new file, then this command lists only the defaults.
Note that this is a good way to learn about new configuration settings,
particularly if your .taskrc file was created by an older version.
.TP
.B Q: Do I need to back up my taskwarrior data?
Yes you do, like all your other files. You should back up all the files in your
~/.task directory, and your ~/.taskrc file too.
.TP
.B Q: Can I share my tasks between different machines?
Yes, you can. Most people have success with a DropBox - a free and secure file
@@ -174,40 +172,25 @@ folder, by modifying the:
configuration variable. Check out DropBox at http://www.dropbox.com.
You might also want to share the same .taskrc file. You can do this by putting an alias in the .bashrc file along the lines of
alias task="task rc:/home/username/Dropbox/mysharedtaskrc"
An alternative to Dropbox is to use the push/pull/merge features built into Taskwarrior. See 'man task-sync' for details.
You might also want to share the same .taskrc file. You can do this by putting
an alias in the .bashrc file along the lines of
alias task="task rc:/home/username/Dropbox/mysharedtaskrc"
.TP
.B Q: I don't want to use dropbox. Is there another way to synchronize my tasks?
Of course. Especially if you want to modify tasks offline on both machines and
synchronize them later on. For this purpose there is a 'merge' command which is
is able to insert the modifications you made to one of your task databases into
a second database.
Here is a basic example of the procedure:
task merge ssh://user@myremotehost/.task/
task push ssh://user@myremotehost/.task/
The first command fetches the undo.data file from the remote system, reads the
changes made and updates the local database. When this merge command completes,
you should copy all the local .data files to the remote system either by using
the push command explicitly or by activating the merge.autopush feature in the
~/.taskrc file. This way you ensure that both systems are fully synchronized.
Yes. Get a Task Server account, and sync tasks between all your machines and
devices. See task-sync(5).
.TP
.B Q: The undo.data file gets very large - do I need it?
You need it if you want the undo capability, or the merge capability mentioned
above. But if it gets large, you can certainly truncate it to save space, just
be careful to delete lines from the top of the file, up to and including a
separator '---'. The simplest way is to simply delete the undo.data file. Note
that it does not slow down taskwarrior in performance-sensitive areas, because
it is typically not read until you want to undo, or report total active time in
the 'info' command. Taskwarrior generally only appends to the file.
You need it if you want the undo capability. But if it gets large, you can
certainly truncate it to save space, just be careful to delete lines from the
top of the file, up to and including a separator '---'. The simplest way is to
simply delete the undo.data file. Note that it does not slow down taskwarrior
in performance-sensitive areas, because it is typically not read until you want
to undo, or report total active time in the 'info' command. Taskwarrior
generally only appends to the file.
It is not recommended that you delete the undo.data file, as it limits
functionality.
@@ -262,7 +245,8 @@ Taskwarrior does this to always show you the smallest numbers it can. The idea
is that if your tasks are numbered 1 - 33, for example, those are easy to type
in. If instead task kept a rolling sequence number, after a while your tasks
might be numbered 481 - 513, which makes it more likely to enter one
incorrectly, because there are more digits.
incorrectly, because there are more digits, and humans have difficulty with
longer numbers.
When you run a report (such as "list"), the numbers are assigned before display.
For example, you can do this:

415
doc/man/task-sync.5.in
View File

@@ -1,362 +1,130 @@
.TH task-sync 5 2013-04-07 "${PACKAGE_STRING}" "User Manuals"
.SH NAME
task-sync \- A tutorial for the task(1) data synchronization capabilities.
task-sync \- A discussion and tutorial for the various task(1) data
synchronization capabilities.
.SH 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.
.SH INTRODUCTION
Taskwarrior has several sync options, external and internal. If you wish to
sync your data, choose one method only; mixing methods is only going to lead to
problems. Each of the methods discussed have their own strengths.
Taskwarrior can use various protocols for transferring the data.
.SH 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.
.SH 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.
.SH MERGE
The merge command will fetch task data via URI and combine it with the local
task database. The syntax is:
.SH ALTERNATIVES
There are three alternatives for syncing data, which are:
1) Version control systems, such as git, hg, svn
.br
.RS
task merge [<URI>]
.RE
The URI is optional if the
.B 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:
2) File hosting systems, such as DropBox
.br
.RS
$ task merge ~/work/
.RE
3) Using the Task Server and the 'sync' command
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.
.SH OPTION 1: VERSION CONTROL SYSTEMS
There are several good VCS systems (git, hg, svn ...), and they function in a
similar fashion for our purposes.
Note that a merge operation is not atomically reversible. You could however
run the 'task undo' command repeatedly to undo the effects.
.SH PUSH
The push command will copy the local task database to the specified URI. The
syntax is:
Setup is straightforward. You place your .task directory under revision
control. You then need to perform a regular commit/push/pull to make sure that
the data is propagated when needed. You can even do this using shell scripts so
that every task command is preceded by a 'pull' and followed by a 'push'.
Strengths:
.br
.RS
task push [<URI>]
.RE
The URI is optional if the
.B 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.
.SH PULL
The pull command will copy a task database from a URI to the local task database
(~/.task by default). The syntax is:
- Good data transport mechanisms
.br
.RS
task pull [<URI>]
.RE
The URI is optional if the
.B 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.
.SH URI TYPES
The most basic URI is a path name on the local machine. An example would be:
- Secure transport options
Weaknesses:
.br
.RS
/home/bob/.task/
.RE
All the other URIs allow access to remote machines. The first uses SSH and scp
(either form can be used):
- You need proficiency with VCS tools
.br
.RS
ssh://[user@]host[:port]/absolute/path/to/.task/
- You will need to manually resolve conflicts frequently
.br
[user@]host:/absolute/path/to/.task/
.RE
- You need to provide the mechanism for making sure copies are up to date
In both cases paths are considered to be absolute. You can specify paths relative to the
users home directory as follows:
.SH OPTION 2: FILE HOSTING SERVICES
There are many file hosting 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
.RS
ssh://[user@]host[:port]/.task/
- Always secure
.br
[user@]host:.task/
.RE
or even shorter
- Good client support
.br
.RS
[user@]host:.task/
.RE
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:
- Easy setup
.br
.RS
ssh://configured-host/~[username]/.task/
- Transparent use
Weaknesses:
.br
configured-host:~[username]/.task/
.RE
- Tasks not properly merged
Rsync is another supported protocol that minimizes network traffic, by a clever
algorithm that doesn't copy files that have not changed:
.SH OPTION 3: TASK SERVER
The Task Server was designed for this purpose to be secure, fast and conflict
free, allowing data interchange between assorted Taskwarrior clients, and
tolerant of network connectivity problems.
There is a 'sync' command built in to Taskwarrior, and with a server account
and client configuration, syncing is done on demand.
Setup is a matter of creating an account on a Task Server (see your Task Server
provider or operate your own - see
http://taskwarrior.org/projects/taskwarrior/wiki/Server_setup)
Once you have an account, you'll receive a certificate, and a password. You'll
need to put the certificate somewhere like this:
$ cp <name>.cert.pem ~/.task
Then you configure Taskwarrior, using the account details:
$ task config taskd.certificate ~/.task/<name>.cert.pem
$ task config taskd.credentials <organization>/<name>/<password>
$ task config taskd.server <server domain>:<port>
After setup, you run a one-time sync initialization, like this:
$ task sync initialize
This will make sure your client and the server are properly in sync to begin
with. From this point on, you never run the 'initialize' command again, just
go about your business, and when you want to sync, run this:
$ task sync
You'll see a summary of how many tasks were uploaded and downloaded. You can
safely run the command as often as you like. When there are no changes to sync,
nothing happens. If you do not have connectivity, your task changes accumulate
so that when you next run 'sync' with proper connectivity, the changes are
properly handled, in the right order.
Strengths:
.br
.RS
rsync://[user@]host.xz[:port]/path/to/.task/
.RE
Curl supports several protocols that can transfer data using HTTP, HTTPS and
FTP:
- Always secure
.br
.RS
http://host[:port]/path/to/.task/
- Minimal bandwidth
.br
https://host[:port]/path/to/.task/
.br
ftp://[user@]host[:port]/path/to/.task/
.RE
- Tolerates connectivity outage
You can use single quotes to encapsulate user names that contain delimiting
characters like '@', '/' or ':', e.g.:
.br
.RS
ssh://'user@name'@host/
.RE
Remember to escape the quotes on your shell:
.br
.RS
$ task push ftp://\'user@name\':host/
.RE
.SH 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.
.SH 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:
.br
.RS
$ task push ~/backup/
.RE
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:
.br
.RS
$ task push user@host:backup
.RE
This could be improved by setting the
.B push.default.uri
configuration variable and then relying on the default, like this:
.br
.RS
$ task config push.default.uri user@host:backup
.RE
and then you need only run the push command:
.br
.RS
$ task push
.RE
and the default push URI will be used. If you wanted to restore a backup, you
simply use the pull command instead:
.br
.RS
$ task pull user@host:backup
.RE
This can be simplified by setting the
.B pull.default.uri
configuration variable and then relying on the default, like this:
.br
.RS
$ task config pull.default.uri user@host:backup
.RE
Note that pull and push will blindly overwrite the task files without any
merging. Be careful.
.SH 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:
.br
.RS
local> task add Deliver the new budget proposal due:tuesday
.br
local> task add Set up a meeting with Bob
.RE
Then later adds a task on the remote machine:
.br
.RS
remote> task add Present the budget proposal at the big meeting due:thursday
.RE
Now on the local machine, Alice merges the two task databases:
.br
.RS
local> task merge alice@remote:.task
.br
Would you like to push the changes to 'alice@remote:.task'? Y
.RE
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:
.br
.RS
remote> task 1 due:wednesday
.RE
Now on the local machine, Alice sets up a default URI and autopush:
.br
.RS
local> task config merge.default.uri alice@remote:.task
.br
local> task config merge.autopush yes
.RE
Now Alice can simply run merge to make sure that the new due date is copied to
the local machine:
.br
.RS
local> task merge
.RE
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.
.SH CONFIGURATION
By setting these configuration variables, it is possible to simplify the
synchronization commands, by relying on the defaults or alias names.
.br
.B merge.autopush=yes|no|ask
.RS
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'.
.RE
.br
.B merge.default.uri=<uri>
.RS
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'.
.RE
.br
.B push.default.uri=<uri>
.RS
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'.
.RE
.br
.B pull.default.uri=<uri>
.RS
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'.
.RE
Note that, when using SSH/scp, hostnames will be expanded due to the ssh
configuration file ~/.ssh/config.
.SH 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.
.SH "CREDITS & COPYRIGHTS"
Copyright (C) 2006 \- 2013 P. Beckingham, F. Hernandez.
The sync capabilities were written by J. Schlatow.
Parts copyright (C) 2010 - 2013 J. Schlatow.
Taskwarrior is distributed under the MIT license. See
http://www.opensource.org/licenses/mit-license.php for more information.
@@ -367,7 +135,6 @@ http://www.opensource.org/licenses/mit-license.php for more information.
.BR task-faq(5),
.BR task-color(5),
.BR task-tutorial(5),
.BR ssh_config(5)
For more information regarding task, the following may be referenced:

30
doc/man/task.1.in
View File

@@ -341,23 +341,6 @@ example scripts, such as import-yaml.pl.
.B task log <mods>
Adds a new task that is already completed, to the task list.
.TP
.B task merge <URL>
Merges two task databases by comparing the modifications that are stored in the
undo.data files. The location of the second undo.data file must be passed on as
argument. URL may have the following syntaxes:
ssh://[user@]host.xz[:port]/path/to/.task/
rsync://[user@]host.xz[:port]/path/to/.task/
[user@]host.xz:path/to/.task/
/path/to/local/.task/
You can set aliases for frequently used URLs in the .taskrc. Further
documentation can be found in the task-sync(5) man page.
.TP
.B task <filter> modify <mods>
Modifies the existing task with provided information.
@@ -366,17 +349,6 @@ Modifies the existing task with provided information.
.B task <filter> prepend <mods>
Prepends description text to an existing task.
.TP
.B task pull <URL>
Overwrites the task database with those files found at the URL.
(See 'merge' command for valid URL syntax.)
.TP
.B task push <URL>
Pushes the task database to a remote location for distributing the
changes made by the merge command.
(See 'merge' command for valid URL syntax.)
.TP
.B task <filter> start <mods>
Marks the specified tasks as started.
@@ -1079,7 +1051,7 @@ The file that contains the completed ("done") tasks.
.TP
~/.task/undo.data
The file that contains information needed by the "undo" and "merge" commands.
The file that contains information needed by the "undo" command.
.SH "CREDITS & COPYRIGHTS"
Copyright (C) 2006 \- 2013 P. Beckingham, F. Hernandez.

27
doc/man/taskrc.5.in
View File

@@ -980,7 +980,7 @@ a change that is to be reverted.
.br
.B color.sync.rejected=red
.RS
Colors the output of the merge command.
Colors the output of the sync command.
.RE
.TP
@@ -1102,31 +1102,6 @@ shadow.notify=on
When this value is set to "on", taskwarrior will display a message whenever the
shadow file is updated by some task command.
.SS PUSH/PULL/MERGE
See the 'man task-synch' page for more details regarding usage.
.TP
.B merge.autopush=yes|no|ask
.RS
Determines post-merge behavior regarding automatic push.
.RE
.B merge.default.uri
.RS
Default merge URI.
.RE
.B pull.default.uri
.RS
Default pull URI.
.RE
.B push.default.uri
.RS
Default push URI.
.RE
.SS DEFAULTS
.TP

28
test/undo.t
View File

@@ -28,7 +28,7 @@
use strict;
use warnings;
use Test::More tests => 11;
use Test::More tests => 16;
# Ensure environment has no influence.
delete $ENV{'TASKDATA'};
@@ -44,12 +44,12 @@ if (open my $fh, '>', 'undo.rc')
ok (-r 'undo.rc', 'Created undo.rc');
}
# Test the add/do/undo commands.
# Test the add/done/undo commands.
my $output = qx{../src/task rc:undo.rc add one 2>&1; ../src/task rc:undo.rc info 1 2>&1};
ok (-r 'pending.data', 'pending.data created');
like ($output, qr/Status\s+Pending\n/, 'Pending');
$output = qx{../src/task rc:undo.rc 1 do 2>&1; ../src/task rc:undo.rc info 1 2>&1};
$output = qx{../src/task rc:undo.rc 1 done 2>&1; ../src/task rc:undo.rc info 1 2>&1};
ok (-r 'completed.data', 'completed.data created');
like ($output, qr/Status\s+Completed\n/, 'Completed');
@@ -65,6 +65,28 @@ $output = qx{../src/task rc:undo.rc undo 1 2>&1};
unlike ($output, qr/Unknown error/, 'No unknown error');
like ($output, qr/The undo command does not allow further task modification/, 'Correct error caught and reported');
# Inspect backlog.data
if (open my $fh, '<', 'backlog.data')
{
my @lines = <$fh>;
close $fh;
diag ($_) for @lines;
is (scalar (@lines), 4, '4 lines of backlog');
ok (index ($lines[0], '"status":"pending"') != -1, '[0] pending');
ok (index ($lines[1], '"status":"completed"') != -1, '[1] completed');
ok (index ($lines[2], '"status":"pending"') != -1, '[2] pending');
ok (index ($lines[3], '"status":"completed"') != -1, '[3] completed');
}
else
{
fail ('4 lines of backlog');
fail ('[0] pending');
fail ('[1] completed');
fail ('[2] pending');
fail ('[3] completed');
}
# Cleanup.
unlink qw(pending.data completed.data undo.data backlog.data undo.rc);
ok (! -r 'pending.data' &&