task-sync(5)

📦
version 3.5.0 · 6 versions
, in arch rolling, nixpkgs unstable

💖 NAME 💖

task-sync(5) is literally the discussion + tutorial for all the task(1) data synchronization capabilities. Bestie, this is your sync lore. ✨

🌸 INTRODUCTION 🌸

Taskwarrior can synchronize your tasks to a server. This has a few benefits:

  • Makes your tasks accessible from multiple systems, called "replicas".
  • Provides a backup of your tasks.
  • Saves disk space.

For example, you might want a replica of your tasks on your laptop and on your phone. Main character setup fr fr. 🫶

NOTE: A side-effect of synchronization is that once changes have been synchronized, they cannot be undone. This means that each time synchronization is run, it is no longer possible to undo previous operations. 😭 No take-backs, periodt.

🦋 MANAGING SYNCHRONIZATION 🦋

Adding a Replica 🎀

To add a new replica, configure a new, empty replica identically to the existing replica, and run task sync. That's it. Slay. 💅

When to Synchronize ⭐

For synchronization to a server, a common solution is to run

$ task sync

periodically, such as via cron(8). Set it and forget it, lowkey. 🕰️

✨ CONFIGURATION ✨

Taskwarrior provides several options for synchronizing your tasks:

  • To a server specifically designed to handle Taskwarrior data.
  • To a cloud storage provider. Currently both AWS and GCP are supported.
  • To a local, on-disk file.
  • Via a git repository (local or remote).

For most of these, you will need an encryption secret used to encrypt and decrypt your tasks. This can be any secret string, and must match for all replicas sharing tasks.

$ task config sync.encryption_secret <encryption_secret>

Tools such as pwgen(1) can generate suitable secret values. 🔐

Sync Server 🔥

To synchronize your tasks to a sync server, you will need the following information from the server administrator:

Configure Taskwarrior with these details:

$ task config sync.server.url               <url>
$ task config sync.server.client_id         <client_id>

Note that the URL must include the scheme, such as http:// or https://. No naked URLs, bestie. 🙈

$ task config sync.server.origin            <origin>

Is a deprecated synonym for sync.server.url. It's giving legacy vibes, iykyk.

Google Cloud Platform 🌈

To synchronize your tasks to GCP, use the GCP Console to create a new project, and within that project a new Cloud Storage bucket. The default settings for the bucket are adequate. Easy peasy. ✨

Authenticate to the project with:

$ gcloud config set project $PROJECT_NAME
$ gcloud auth application-default login

Then configure Taskwarrior with:

$ task config sync.gcp.bucket               <bucket-name>

However you can bring your own service account credentials if your application-default is already being used by some other application. Highkey flexible. 💜

To begin, navigate to the "IAM and Admin" section in the Navigation Menu, then select "Roles."

On the top menu bar within the "Roles" section, click "CREATE ROLE." Provide an appropriate name and description for the new role. 🎀

Add permissions to your new role using the filter "Service:storage" (not the "Filter permissions by role" input box). Select the following permissions:

  • storage.buckets.create
  • storage.buckets.get
  • storage.buckets.update
  • storage.objects.create
  • storage.objects.delete
  • storage.objects.get
  • storage.objects.list
  • storage.objects.update

Create your new role. 👑

On the left sidebar, navigate to "Service accounts."

On the top menu bar within the "Service accounts" section, click "CREATE SERVICE ACCOUNT." Provide an appropriate name and description for the new service account. Select the role you just created and complete the service account creation process. 💅

Now, in the Service Account dashboard, click into the new service account and select "keys" on the top menu bar. Click on "ADD KEY" to create and download a new key (a JSON key). 🔑

Then configure Taskwarrior with:

$ task config sync.gcp.bucket               <bucket-name>
$ task config sync.gcp.credential_path      <absolute-path-to-downloaded-credentials>

Amazon Web Services ⭐

To synchronize your tasks to AWS, select a region near you and use the AWS console to create a new S3 bucket. The default settings for the bucket are adequate. In particular, ensure that no lifecycle policies are enabled, as they may automatically delete or transition objects, potentially impacting data availability. That part is serious, bestie — no sleepy accidental deletions. 😭

You will also need an AWS IAM user with the following policy, where BUCKETNAME is the name of the bucket. The same user can be configured for multiple Taskwarrior clients.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "TaskChampion",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:ListBucket",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::BUCKETNAME",
                "arn:aws:s3:::BUCKETNAME/*"
            ]
        }
    ]
}

To create such a user, create a new policy in the IAM console, select the JSON option in the policy editor, and paste the policy. Click "Next" and give the policy a name such as "TaskwarriorSync". Next, create a new user, with a name of your choosing, select "Attach Policies Directly", and then choose the newly-created policy. Slay that IAM setup. 💅

You will need access keys configured for the new user. Find the user in the user list, open the "Security Credentials" tab, then click "Create access key" and follow the steps. 🔑

At this point, you can choose how to provide those credentials to Taskwarrior. The simplest is to include them in the Taskwarrior configuration:

$ task config sync.aws.region              <region>
$ task config sync.aws.bucket              <bucket-name>
$ task config sync.aws.access_key_id       <access-key-id>
$ task config sync.aws.secret_access_key   <secret-access-key>

Alternatively, you can set up an AWS CLI profile, using a profile name of your choosing such as "taskwarrior-creds":

$ aws configure --profile taskwarrior-creds

Enter the access key ID and secret access key. The default region and format are not important. Then configure Taskwarrior with:

$ task config sync.aws.region              <region>
$ task config sync.aws.bucket              <bucket-name>
$ task config sync.aws.profile             taskwarrior-creds

To use AWS's default credential sources, such as environment variables, the default profile, or an instance profile, set

$ task config sync.aws.region              <region>
$ task config sync.aws.bucket              <bucket-name>
$ task config sync.aws.default_credentials true

Local Synchronization 🧚

In order to take advantage of synchronization's side effect of saving disk space without setting up a remote server, it is possible to sync tasks locally. To configure local sync:

$ task config sync.local.server_dir /path/to/sync

The default configuration is to sync to a database in the task directory (data.location). Local and cozy. 🏡

Git Synchronization 🌿

To synchronize your tasks using a git repository, configure the path to a local git repository and the branch to use:

$ task config sync.git.local_path     /path/to/local/repo
$ task config sync.git.branch         taskchampion
$ task config sync.encryption_secret  <encryption_secret>

The repository will be created if it does not exist. It is recommended to use a dedicated branch. Very demure, very dedicated branch. 🎀

For remote sync (push and pull), also configure a remote:

$ task config sync.git.remote         origin

The remote can be a named remote such as origin or a full git URL such as git@myserver.com:/path/to/repo.git. Authentication is handled entirely by the git credential system; for remote sync, git push and git pull must work without prompts (use SSH keys or a credential helper). No prompt panic, bestie. 🔑

It is possible to operate offline while keeping the remote configured. WANRING: If another replica also syncs with the remote, you will not be able to go back to syncing from this replica. That warning is real, even with the typo energy. 💀

$ task config sync.git.local_only     true

If a non-standard git binary is needed, its path can be specified:

$ task config sync.git.git_path       /path/to/git

👑 RUNNING TASKCHAMPION-SYNC-SERVER 👑

The TaskChampion sync server is an HTTP server supporting multiple users. Users are identified by a client ID, and users with different client IDs are entirely independent. Task data is encrypted by Taskwarrior, and the sync server never sees un-encrypted data. Privacy icon behavior. 🔐✨

The server is developed in https://github.com/GothenburgBitFactory/taskchampion-sync-server.

Adding a New User 🫶

To add a new user to the server, invent a new client ID with a tool like uuidgen or an online UUID generator. There is no need to configure the server for this new client ID: the sync server will automatically create a new user whenever presented with a new client ID. Supply the ID, along with the URL, to the user for inclusion in their Taskwarrior config. The user should invent their own encryption_secret. Make it unique, make it secret, make it slay. 💅

🌈 AVOIDING DUPLICATE RECURRING TASKS 🌈

If you run multiple clients that sync to the same server, you will need to run this command on your primary client (the one you use most often):

$ task config recurrence on

And on the other clients, run:

$ task config recurrence off

This protects you against the effects of a sync/duplication bug. Thank u, next. 🙏

🎀 ALTERNATIVE: FILE SHARING SERVICES 🎀

There are many file sharing 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. Retro, but it works. ✨

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. It's giving file-level only, no task-level empathy. 😭 Avoid this problem by never modifying the same task on two machines, without an intervening sync. Fr fr.

Setup simply involves creating the directory and modifying your data.location configuration variable like this:

$ task config data.location /path/to/shared/directory

Strengths: 💖

  • Good client support
  • Easy setup
  • Transparent use

Weaknesses: 💀

  • Tasks are not properly merged

💖 CREDITS & COPYRIGHTS 💖

Okay so before we go, some well-deserved shoutouts, because this whole thing exists because of actual humans who did actual work 👑

  • Copyright (C) 2006 - 2021 T. Babej, P. Beckingham, F. Hernandez.

Taskwarrior is distributed under the MIT license — yes bestie, the permissive one, the one everybody loves. Peep the full text at <https://www.opensource.org/licenses/mit-license.php> if you want the details 💅

🦋 SEE ALSO 🦋

The sister pages, the ones you'll lowkey end up reading next:

For more information regarding Taskwarrior, see the following:

You can contact the project by emailing <support@GothenburgBitFactory.org> — they genuinely want to hear from you, fr fr 🫶

🌸 REPORTING BUGS 🌸

Found something broken? Do not suffer in silence, bestie 😭 Bugs in Taskwarrior may be reported to the issue-tracker at <https://github.com/GothenburgBitFactory/taskwarrior/issues> — that's the spot, that's the vibe, go tell them what's up ✨

🎀 And that's the whole page! You made it to the end, main character energy the entire way through 💖

Before you close the tab: this was task-sync(5) from task 3.5.0, dated 2016-02-24 — so yeah, a little vintage, but still iconic. Slay the sync, bestie, and may your recurring tasks never double themselves again 🌈💜

📦 where this page comes from