DOCSEARCHbyAlgolia
Submit Docs

Taskwarrior Documentation

repository·develop·Indexed 26 days ago

https://github.com/gothenburgbitfactory/taskwarrior

A feature-rich, portable command-line task management utility. This documentation covers general usage, installation across Linux, macOS, and Windows, and detailed development guides including build workflows with CMake, C++ and Rust coding styles, and the integration with the TaskChampion storage backend.

Tokens
27.9K
Snippets
77
Records
240
Agent score
90%

What's inside Taskwarrior

  2. Locate Taskwarrior documentation

    develop

    Taskwarrior documentation is distributed in several formats and locations depending on your needs:

    • Manual Pages: The source for manual pages is located in the man/ directory.
    • Configuration Files (rcfiles): Configuration templates and rcfiles are located in the rc/ directory. These are typically installed to /usr/share/doc/task/rc or an equivalent system path.
    • Reference Documentation: General reference documentation is located in the ref/ directory. These are typically installed to /usr/share/doc/task or an equivalent system path.

  5. Understand the Taskwarrior and TaskChampion relationship

    develop

    Since the 3.0 release, Taskwarrior utilizes TaskChampion for task data management. If you are developing features related to data storage or task management, you should consult the TaskChampion documentation:

  6. Understand the TaskChampion storage backend

    develop
    TaskChampion is a Rust library that provides the storage backend for Taskwarrior (as of version 3.0.0). It manages "replicas" containing user tasks and defines an abstract data model for them. TaskChampion provides a Rust API for manipulating replicas and includes a sync server implementation for synchronizing replicas across different locations. Other applications can use TaskChampion as a task management interface independently of Taskwarrior.

  7. Understand the Taskserver Sync Algorithm

    develop

    The Taskserver uses a sync algorithm to merge task changes from multiple sources (e.g., local machines and the server) into a single, conflict-free state. The algorithm functions similarly to an SCM (Source Control Management) rebase.

    Key concepts:

    • Deltas: A change is represented as a delta ($d$), which is the transform applied to a base task ($T_0$) to reach a new state ($T_1$). Formula: $d_1 = T_1 - T_0$.
    • Two-Branch Case: When changes occur simultaneously on a client and the server, the algorithm treats them as two parallel sequences starting from the same base task.
    • Ordering: Because deltas are not commutative (the order of application matters), the Taskserver uses the task's last modified time metadata to determine the correct sequence of application.
    • Serial Processing: Multiple client sync requests are processed serially, meaning the algorithm only ever needs to resolve a two-branch case at any given moment.

  8. Understand Taskwarrior recurrence terminology

    develop

    The recurrence system uses specific terminology to manage recurring tasks:

    • Template: The hidden task that defines the recurrence rules (formerly called parent).
    • Synthesis: The process of generating new recurring task instances when necessary.
    • Instances: The individual tasks generated from a template.
    • Index: The zero-based, monotonically increasing number of an instance.
    • Drift: Accumulated errors in time that can cause due dates to shift for recurring tasks.
    • rtype: The recurrence type (flavor) of the task.

  9. Run the Taskwarrior test suite

    develop

    The test suite is managed via ctest. Before running tests, you must build both the task_executable and the test_runner target.

    Test Execution Commands:

    • Run all tests: ctest --test-dir build
    • Parallel execution: Use -j <number-of-jobs> to run tests in parallel.
    • Filter by regex: Use -R <regex> to run only tests matching a specific pattern (e.g., -R cpp for C++ tests).
    • Handle failures: It is recommended to use --output-on-failure for verbose error reporting and --rerun-failed to retry only failed tests.
    • Debug sporadic failures: Use --repeat-until-fail <count> to run a specific test multiple times to catch intermittent issues.

  11. Build Taskwarrior from source

    develop

    Perform an out-of-source build using CMake. The primary executable is located at build/src/task after a successful build.

    Basic Build Workflow:

    1. Clone the repository and initialize submodules.
    2. Configure the build directory with a specific build type (e.g., RelWithDebInfo, Release, or Debug).
    3. Build the project.

    Build Options:

    • Specific Target: To build only the task executable, use the --target task_executable flag.
    • Parallel Build: Use -j <number-of-jobs> to speed up the build process.
    • Clang Compiler: To force the use of clang and clang++, configure a separate build directory (e.g., build-clang) using the CMAKE_C_COMPILER and CMAKE_CXX_COMPILER flags.