## 1. Project Overview & Quickstart (GothenburgBitFactory/taskwarrior) ## File: README.md ## Taskwarrior Taskwarrior is a command line task list management utility with a [multitude of features](https://taskwarrior.org/docs/), developed as a portable open source project with an active and quite vast [ecosystem of tools, hooks and extensions](https://taskwarrior.org/tools/). ## Install [](https://archlinux.org/packages/extra/x86_64/task/) [](https://packages.debian.org/search?keywords=task&searchon=names&suite=all§ion=all) [](https://bodhi.fedoraproject.org/updates/?packages=task) [](https://formulae.brew.sh/formula/task#default) [](https://packages.ubuntu.com/search?keywords=task&searchon=names&suite=hirsute§ion=all) Taskwarrior is packaged on a wide range of [Linux/Unix systems, Mac OS and Windows](https://taskwarrior.org/download/). Check out the latest available packages in repositories of your OS distribution of choice [on Repology](https://repology.org/project/taskwarrior/versions). Alternatively, you can [build Taskwarrior from source](doc/devel/contrib). ## Documentation The [online documentation](https://taskwarrior.org/docs), downloads, news and more are available on our website, [taskwarrior.org](https://taskwarrior.org). ## Community [](https://discord.gg/eRXEHk8w62) [](https://github.com/GothenburgBitFactory/taskwarrior/discussions) [](https://reddit.com/r/taskwarrior/) Taskwarrior has a lively community on many places on the internet. Best place to ask questions is our [discussions forum on Github](https://github.com/GothenburgBitFactory/taskwarrior/discussions). For other support options, take a look at [taskwarrior.org/support](https://taskwarrior.org/support) For code contributions, please use pull requests. See [Contributing to Taskwarrior](doc/devel/contrib) for more details. ## Contributing [](https://github.com/GothenburgBitFactory/taskwarrior/graphs/contributors) [](https://github.com/GothenburgBitFactory/taskwarrior/milestone/26) [](https://github.com/GothenburgBitFactory/taskwarrior/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) Your contributions are especially welcome. Whether it comes in the form of code patches, ideas, discussion, bug reports, encouragement or criticism, your input is needed. See further development documentation in [`doc/devel`](./doc/devel). ## Sponsoring [](https://github.com/sponsors/GothenburgBitFactory/) Taskwarrior is a result of work of mostly small group of volunteers, and has been in development since 2006. If you are a happy Taskwarrior user, please consider [sponsoring us through Github Sponsors](https://github.com/sponsors/GothenburgBitFactory/). Every sponsorship matters, as it directly increases the number of hours core developers can contribute to the project and makes the project more sustainable. ## License Taskwarrior is released under the MIT license. For details check the [LICENSE](LICENSE) file. --- ## File: doc/devel/contrib/branching.md Software development typically requires a standardized branching model, to manage complexity and parallel efforts. The branching model can be a source of confusion for developers, so this document describes how branching is used. We use the following branching model: * `develop` is the current development branch. All work is done here, and upon release it will be branched to a release branch. While `develop` is not stable, we utilize CI to ensure we're at least not merging improvements that break existing tests, and hence should be relatively safe. We still recommend making backups when using the development branch. * The most recent minor release is in a branch named after the release, e.g., `2.7.0`. This branch is used for bug-fixes of the latest release. --- ## File: doc/devel/contrib/coding_style.md # Coding Style The coding style used for the Taskwarrior is based on the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html), with small modifications in the line length. # Automatic formatting In order to have consistancy and automatic formatting [pre-commit](https://pre-commit.com) is used to apply [clang-format](https://clang.llvm.org/docs/ClangFormat.html) and [black](https://github.com/psf/black) are used. In order to set them up locally please run: ```python pip install pre-commit pre-commit install ``` For more information refer to the [quick-start of pre-commit](https://pre-commit.com/#quick-start). The setup is also included in the CI, hence if one can not install it automatically then the CI will take care for it in the PR. ## Rust Rust code should be formatted with `rustfmt` and generally follow Rust style guidelines. --- ## File: doc/devel/contrib/development.md # Developing Taskwarrior ## Satisfy the Requirements: * CMake 3.22 or later * gcc 7.0 or later, clang 6.0 or later, or a compiler with full C++17 support * libuuid (if not on macOS) * Rust 1.64.0 or higher (hint: use https://rustup.rs/ instead of using your system's package manager) ## Install Optional Dependencies: * python 3 (for running the test suite) * pre-commit (for applying formatting changes locally) * clangd or ccls (for C++ integration in many editors) * rust-analyzer (for Rust integration in many editors) ## Obtain and Build Code: The following documentation works with CMake 3.14 and later. Here are the minimal steps to get started, using an out of source build directory and calling the underlying build tool over the CMake interface. See the general CMake man pages or the [cmake-documentation](https://cmake.org/cmake/help/latest/manual/cmake.1.html) for more, ## Basic Building ```sh git clone https://github.com/GothenburgBitFactory/taskwarrior cd taskwarrior git submodule init git submodule update cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo cmake --build build ``` Other possible build types can be `Release` and `Debug`. This will build several executables, but the one you want is probably `src/task`, located in the `build` directory. When you make changes, just run the last line again. ### Building a specific target For **only** building the `task` executable, use ```sh cmake --build build --target task_executable ``` ### Building in parallel If a parallel build is wanted use ```sh cmake --build build -j ``` ### Building with clang as compiler ```sh cmake -S . -B build-clang\ -DCMAKE_C_COMPILER=clang\ -DCMAKE_CXX_COMPILER=clang++ cmake --build build-clang ``` ## Run the Test Suite: For running the test suite [ctest](https://cmake.org/cmake/help/latest/manual/ctest.1.html) is used. Before one can run the test suite the `task_executable` must be built. After that also the `test_runner` target must be build, which can be done over: ```sh cmake --build build --target test_runner ``` Again you may also use the `-j ` option for parallel builds. Now one can invoke `ctest` to run the tests. ```sh ctest --test-dir build ``` This would run all the test in serial and might take some time. ### Running tests in parallel ```sh ctest --test-dir build -j ``` Further it is adviced to add the `--output-on-failure` option to `ctest`, to recieve a verbose output if a test is failing as well as the `--rerun-failed` flag, to invoke in subsequent runs only the failed ones. ### Running specific tests For this case one can use the `-R ` or `--tests-regex ` option to run only the tests matching the regular expression. Running only the `cpp` tests can then be achieved over ```sh ctest --test-dir build -R cpp ``` or running the `variant_*` tests ```sh ctest --test-dir build -R variant ``` ### Repeating a test case In order to find sporadic test failures the `--repeat` flag can be used. ```sh ctest --test-dir build -R cpp --repeat-until-fail 10 ``` There are more options to `ctest` such as `--progress`, allowing to have a less verbose output. They can be found in the [ctest](https://cmake.org/cmake/help/latest/manual/ctest.1.html) man page. Note that any development should be performed using a git clone, and the current development branch. The source tarballs do not reflect HEAD, and do not contain the test suite. Follow the [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) for creating a pull request. ## Using a Custom Version of TaskChampion To build against a different version of Taskchampion, modify the requirement in `src/taskchampion-cpp/Cargo.toml`. To build from a local checkout, replace the version with a [path dependency](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-path-dependencies), giving the path to the directory containing TaskChampion's `Cargo.toml`: ```toml taskchampion = { path = "path/to/taskchampion" } ``` --- ## File: doc/devel/contrib/first_time.md # Welcome, Open Source Contributor Welcome, potential new Open Source contributor! This is a guide to show you exactly how to make a contribution, and will lead you through the entire process. There are many people who wish to start contributing, but don't know how or where to start. If this might be the case for you, then please read on, this guide is for you. Because we want you to join in the fun with Open Source - it can be fun and rewarding, improve your skills, or just give you a way to contribute back to a project. ## How to Help Help is needed in all areas of Taskwarrior development - design, coding, testing, support and marketing. Applicants must be friendly. Perhaps you are looking to help, but don't know where to start. Perhaps you have skills we are looking for, here are ways you may be able to help: - Use Taskwarrior, become familiar with it, and make suggestions. We get great feedback from both new users and veteran users. New users have a fresh approach that we can no longer achieve, while veteran users develop clever and crafty ways to use the product. - Report bugs and odd behavior when you see it. We don't necessarily know it's broken, unless you tell us. - Suggest enhancements. We get lots of these, and it's great. Some really good ideas have been suggested and implemented. Sure, some are out of scope, or plain crazy, but the stream of suggestions is fascinating to think about. - Participate in the [bug tracking](https://github.com/GothenburgBitFactory/taskwarrior/issues) database, to help others and maybe learn something yourself. - Proofread the documentation and man pages. - Improve the documentation. - Improve the man pages. - Help improve the tutorials. Make your own tutorial. - Confirm a bug. Nothing gets fixed without confirmation. - Refine a bug. Provide relevant details, elaborate on the behavior. - Fix a bug. Send a patch. For this you'll need to know some C++ or Rust, and understand the [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow). See [Developing Taskwarrior](./development.md) for more information. We welcome all bug fixes, provided the work is done well and doesn't create other problems or introduce new dependencies. We recommend talking to us before starting: we are happy to help you out! - Write a unit test. Unit tests are possibly the most useful contributions of all, because they not only improve the quality of the code, but prevent future regressions, therefore maintaining quality of subsequent releases. Plus, broken tests are a great motivator for us to fix the causal defect. You'll need Python skills. - Spread the word. Help others become more effective at managing tasks. Share your methodology, to inspire others. - Encouragement. Tell us what works for you, and what doesn't. It's all good. - Donate! Help offset costs. Please remember that we need contributions from all skillsets, however small. Every contribution helps. --- ## File: doc/devel/contrib/README.md # Contributing To Taskwarrior * [Welcome, Open Source Contributor](first_time.md) * [Developing Taskwarrior](development.md) * [Coding Style](coding_style.md) * [Branching Model](branching.md) * [Rust and C++](rust-and-c++.md) * [Releasing Taskwarrior](releasing.md) --- ## File: doc/devel/contrib/releasing.md # Releasing Taskwarrior To release Taskwarrior, follow this process: - Examine the changes since the last version, and update `src/commands/CmdNews.cpp` accordingly. There are instructions at the top of the file. This is typically only required for minor and major versions. - Create a release PR - Update version in CMakeLists.txt - Update Changelog - get this merged - On `develop` after that PR merges, create a release tarball: - `git clone . release-tarball` - `cd release-tarball/` - `cmake -S. -Bbuild` - `make -Cbuild package_source` - copy build/task-*.tar.gz elsewhere and delete the `release-tarball` dir - NOTE: older releases had a `test-*.tar.gz` but it's unclear how to generate this - Update `stable` to the released commit and push upstream - Tag the commit as vX.Y.Z and push the tag upstream - Find the tag under https://github.com/GothenburgBitFactory/taskwarrior/tags and create a release from it - Give it a clever title if you can think of one; refer to previous releases - Include the tarball from earlier - Update https://github.com/GothenburgBitFactory/tw.org (but see https://github.com/GothenburgBitFactory/tw.org/pull/1269) - Add a new item in `content/news` - Update `data/projects.json` with the latest version and a fake next version for "devel" - Update `data/releases.json` with the new version, linking to the GitHub release. Get the sha256 from the file you copied earlier. - Update various things, in a new PR: - `cargo update` - `git submodule update --remote --merge` --- ## File: doc/devel/contrib/rust-and-c++.md # Rust and C++ Taskwarrior has historically been a C++ project, but as of taskwarrior-3.0.0, the storage backend is now provided by a Rust library called TaskChampion. ## TaskChampion TaskChampion implements storage and access to "replicas" containing a user's tasks. It defines an abstract model for this data, and also provides a simple Rust API for manipulating replicas. It also defines a method of synchronizing replicas and provides an implementation of that method in the form of a sync server. Other applications, besides Taskwarrior, can use TaskChampion to manage tasks. Taskwarrior is just one application using the TaskChampion interface. ## Taskwarrior's use of TaskChampion Taskwarrior's interface to TaskChampion is in `src/taskchampion-cpp`. This links to `taskchampion` as a Rust dependency, and uses [cxx](https://cxx.rs) to build a C++ API for it. That API is defined, and documented, in `src/taskchampion-cpp/src/lib.rs`, and available in the `tc` namespace in C++ code. --- ## File: doc/devel/rfcs/cli.md --- title: "Taskwarrior - Command Line Interface" --- ## Work in Progress This design document is a work in progress, and subject to change. Once finalized, the feature will be scheduled for an upcoming release. # CLI Syntax Update The Taskwarrior command line syntax is being updated to allow more consistent and predictable results, while making room for new features. Adding support for arbitrary expressions on the command line has become complicated because of the relaxed syntax of Taskwarrior. While the relaxed syntax allows for a very expressive command line, it also creates ambiguity for the parser, which needs to be reduced. With some limited and careful changes it will be possible to have a clear and unambiguous command line syntax, which means a predictable and deterministic experience. It should be stated that for straightforward and even current usage patterns, the command line will likely not change for you. Another goal is to not require changes to 3rd-party software, where possible. Only the more advanced and as-yet unintroduced features will require a more strict syntax. This is why now is an ideal time to tighten the requirements. ## Argument Types The argument types supported remain the same, adding some new constructs. * Config file override * `rc:` * Configuration override * `rc::` Literal value * `rc:=` Literal value * `rc::=` Calculated value * Tag * `+` * `-` * `'+tag one'` Multi-word tag * Attribute modifier * `rc:.:` * Modifier is one of: * `before` * `after` * `under` * `over` * `above` * `below` * `none` * `any` * `is` * `isnt` * `equals` * `not` * `contains` * `has` * `hasnt` * `left` * `right` * `startswith` * `endswith` * `word` * `noword` * Search pattern * `//` * Substitution * `///` * `///g` * Command * `add` * `done` * `delete` * `list` * etc. * Separator * `--` * ID Ranges * `[-<id>][,[-<id>]...]` * UUID * `` * Everything Else * `` * `' ...'` ## New Command Line Rules Certain command line constructs will no longer be supported, and this is imposed by the new rules: 1. Each command line argument may contain only one instance of one argument type, unless that type is ``. task add project:Home +tag Repair the thing # Good task add project:Home +tag 'Repair the thing' # Good task add 'project:Home +tag Repair the thing' # Bad Putting two arguments into one quoted arg makes that arg a ``. 2. If an argument type contains spaces, it must either be quoted or escaped. task add project:'Home & Garden' ... # Good task add 'project:Home & Garden' ... # Good task add project:Home\ \&\ Garden ... # Good task add project:Home' & 'Garden ... # Good task add project:Home \& Garden ... # Bad The parser will not combine multiple arguments, for example: task '/one two/' list # Good task /one two/ list # Bad task /'one two'/ list # Bad, unless ' is part of the pattern 3. By default, *no* calculations are made, unless the `:=` eval operator is used, and if so, the whole argument may need to be quoted or escaped to satisfy Rule 1. task add project:3.project+x # Literal task add project:=3.project+x # DOM reference + concatenation 4. Bare word search terms are no longer supported. Use the pattern type argument instead. task /foo/ list # Good task foo list # Bad 5. Expressions must be a series of arguments, not a quoted string. task urgency \< 5.0 list # Good task 'urgency < 5.0 list' # Bad ## Other Changes Aside from the command line parser, there are other changes needed: - Many online documents will need to be modified. - Filters will be automatically parenthesized, so that every command line will now looke like: task [overrides] [(cli-filter)] [(context-filter)] [(report-filter)] command [modifications] - There will be more errors when the command line is not understood. - Ambiguous ISO date formats are dropped. YYYYMMDD # Bad YYYY-MM-DD # Good hhmmss # Bad hh:mm:ss # Good - The tutorial videos will be even more out of date, and will be replaced by a large number of smaller demo 'movies'. --- ## File: doc/devel/rfcs/client.md --- title: "Taskwarrior - Creating a Taskserver Client" --- # Creating a Taskserver Client A Taskserver client is a todo-list manager. It may be as simple as a program that captures a single task, as complex as Taskwarrior, or anything in between. It can be a mobile client, a web application, or any other type of program. This document describes how such a client would interact with the server. A client to the Taskserver is a program that manages a task list, and wishes to exchange data with the server so that the task list may be shared. In order to do this, a client must store tasks locally, upload local changes, download remote changes, and apply remote changes to the local tasks. The client must consider that there may be no network connectivity, or no desire by the user to synchronize. The client will need proper credentials to talk to the server. ## Requirements In this document, we adopt the convention discussed in Section 1.3.2 of [RFC1122](https://tools.ietf.org/html/rfc1122#page-16) of using the capitalized words MUST, REQUIRED, SHOULD, RECOMMENDED, MAY, and OPTIONAL to define the significance of each particular requirement specified in this document. In brief: "MUST" (or "REQUIRED") means that the item is an absolute requirement of the specification; "SHOULD" (or "RECOMMENDED") means there may exist valid reasons for ignoring this item, but the full implications should be understood before doing so; and "MAY" (or "OPTIONAL") means that this item is optional, and may be omitted without careful consideration. ## Taskserver Account A Taskserver account must be created. This process creates a storage area, and generates the necessary credentials. ## Credentials A Taskserver client needs the following credentials in order to communicate with a server: - Server address and port - Organization name - User name - Password - Certificate - Key The server address and port are the network location of the server. An example of this value is: foo.example.com:53589 In addition to a DNS name, this can be an IPv4 or IPv6 address. The organization name is an arbitrary grouping, and is typically 'PUBLIC', reflecting the individual nature of server accounts. Future capabilities will provide functionality that support groups of users, called an organization. The user name is the full name. This will be the name used to identify other users in an organization, in a future release. Example 'John Doe'. The password is a text string generated by the server at account creation time. It should be considered a secret. The certificate is an X.509 PEM file generated by the server at account creation time. This is used for authentication. It should be considered a secret. The key is an X.509 PEM file generated by the server at account creation time. This is used for encryption. It should be considered a secret. These credentials need to be stored on the client, and used during the sync operation. ## Description of a Taskserver Client This section describes how a client might behave in order to facilitate integration with the Taskserver. ## Encryption The Taskserver only communicates using encryption. Therefore all user data is encrypted while in transit. The Taskserver currently uses [GnuTLS](https://gnutls.org) to support this encryption, and therefore supports the following protocols: - SSL 3.0 - TLS 1.0 - TLS 1.1 - TLS 1.2 The client may use any library that supports the above. ## Configuration The client needs to store configuration, which matches the credentials needed for Taskserver communication. See section 2.1 "Credentials". The credentials may not be modified by the user without losing server access. The server:port data may need to be changed automatically following a redirect response from the server. See section 5 "Server Errors". ## Local Storage The client needs to store task data locally. The client will need to be able to find tasks by their UUID and overwrite them. Uploaded and downloaded task changes will use the [Taskwarrior Data Interchange Format](/docs/design/task). ## Local Changes Whenever local data is modified, that change MUST be synced with the server. But this does not have to occur immediately, in fact the client SHOULD NOT assume connectivity at any time. A client SHOULD NOT also assume that the server is available. If the server is not available, the local changes should be retained, and the sync operation repeated later. Ideally the client will give the user full control over sync operations. Automatically syncing after all local modifications is not recommended. If a client performs too many sync operations, the server MAY revoke the certificate. Effectively, the client should maintain a separate list of tasks changed since the last successful sync operation. Note that tasks have a "modified" attribute, which should be updated whenever a change is made. This attribute contributes to conflict resolution on the server. ## Remote Changes When a server sends remote changes to a client, in the response to a sync request, the changes have already been merged by the server, and therefore the client should simply store them intact. Based on the UUID in the task, the client can determine whether a task is new (and should be added to the local list of tasks), or whether it represents a modification (and should overwrite it's existing entry). The client MUST NOT perform any merges. ## Sync Key Whenever a sync is performed, the server responds by sending a sync key and any remote changes. The sync key is important, and should be included in the next sync request. The client is REQUIRED to store the sync key in every server response message. If a client omits the sync key in a sync message, the response will be a complete set of all tasks and modifications. ## Data Integrity Although a task is guaranteed to contain at least 'entry', 'description' and 'uuid' attributes, it may also contain other known fields, and unknown user-defined fields. An example might be an attribute named 'estimate'. If a task is received via sync that contains an attribute named 'estimate', then a client has the responsibility of preserving the attribute intact. If that data is shown, then it is assumed to be of type 'string', which is the format used by JSON for all values. Conversely, if a client wishes to add a custom attribute, it is guaranteed that the server and other clients will preserve that attribute. Using this rule, two clients of differing capabilities can exchange data and still maintain custom attributes. This is a requirement. Any client that does not obey this requirement is broken. ## Synchronizing Synchronizing with the Taskserver consists of a single transaction. Once an encrypted connection is made with the server, the client MUST compose a [sync request message](/docs/design/request). This message includes credentials and local changes. The response message contains status and remote changes, which MUST be stored locally. ## Establishing Encrypted Connection All communication with the Taskserver is encrypted using the certificate and key provided to each user. Using the 'server' configuration setting, establish a connection. ## Sync Request See [sync request message](/docs/design/request). A sync request MUST contain a sync key if one was provided by a previous sync. A sync request MUST contain a list of modified tasks, in JSON format (see [Task JSON](/docs/design/task)), if local modifications have been made. ## Sync Response A sync response WILL contain a 'code' and 'status' header variable, WILL contain a sync key in the payload, and MAY contain a list of tasks from the server in JSON format (see [Task JSON](/docs/design/task)). ## Server Messages There are cases when the server needs to inform the user of some condition. This may be anticipated server downtime, for example. The response message is typically not present, but may be present in the header, containing a string: ... message: Scheduled maintenance 2013-07-14 08:00UTC for 10 minutes. ... If such a message is returned by the server, it SHOULD be made available to the user. This is a recommendation, not a requirement. ## Server Errors The server may generate many errors (See [Protocol](/docs/design/protocol)), but the following is a list of the ones most in need of special handling: - 200 Success - 201 No change - 301 Redirect - 430 Access denied - 431 Account suspended - 432 Account terminated - 5xx Error The 200 indicates success, and that a change was recorded. The 201 indicates success but no changes were necessary. The 301 is a redirect message indicating that the client MUST re-request from a new server. The 43x series messages are account-related. Any 5xx series code is a server error of some kind. All errors consist of a code and a status message: code: 200 status: Success ## Examples Here are examples of properly formatted request and response messages. Note that the messages are indented for clarity in this document, but is not the case in a properly formatted message. Also note that newline characters U+000D are not shown, but are implied by the separate lines. Because some messages have trailing newline characters, the text is delimited by the 'cut' markers: foo The example above illustrates text consisting of: U+0066 f U+006F o U+006F o U+000D newline U+000D newline Note that these values are left unspecified, but should be clear from the context, and the [message format](/docs/design/request) spec: ## First Sync The first time a client syncs, there is (perhaps) no data to upload, and no sync key from a previous sync. type: sync org: user: key: client: task 2.3.0 protocol: v1 Note the double newline character separating header from payload, with an empty payload. ## Request: Sync No Data Ordinarily when a client syncs, there is a sync key from the previous sync response to send. This example shows a sync with no local changes, but a sync key from a previous sync. type: sync org: user: key: client: task 2.3.0 protocol: v1 2e4685f8-34bc-4f9b-b7ed-399388e182e1 ## Request: Sync Data This sync request shows a sync key from the previous sync, and a locally modified task. type: sync org: user: key: client: task 2.3.0 protocol: v1 2e4685f8-34bc-4f9b-b7ed-399388e182e1 {"description":"An example","uuid":"8ad2e3db-914d-4832-b0e6-72fa04f6e331",...} ## Response: No Data If a sync results in no downloads to the client, the response will look like this. type: response client: taskd 1.0.0 protocol: v1 code: 200 status: Ok 45da7110-1bcc-4318-d33e-12267a774e0f Note that there is a sync key which must be stored and used in the next sync request, but there are no remote changes to store. ## Response: Remote Data This shows a sync response providing a new sync key, and a remote change to two tasks. type: response client: taskd 1.0.0 protocol: v1 code: 200 status: Ok 45da7110-1bcc-4318-d33e-12267a774e0f {"description":"Test data","uuid":"8ad2e3db-914d-4832-b0e6-72fa04f6e331",...} {"description":"Test data2","uuid":"3b6218f9-726a-44fc-aa63-889ff52be442",...} Note that the sync key must be stored for the next sync request. Note that the two changed tasks must be stored locally, and if the UUID in the tasks matches local tasks, then the local tasks must be overwritten. ## Response: Error type: response client: taskd 1.0.0 protocol: v1 code: 431 status: Account suspended Note the double newline character separating header from payload, with an empty payload. ## Response: Relocate type: response client: taskd 1.0.0 protocol: v1 code: 301 status: Redirect info: Note the 'info' field will contain a ':' string that should be used for all future sync requests. This indicates that a user account was moved to another server. Note the double newline character separating header from payload, with an empty payload. ## Response: Message Occasionally the server will need to convey a message, and will include an additional header variable containing that message. The server [protocol](/docs/design/protocol) states that the message SHOULD be shown to the user. This message will be used for system event messages, used rarely, and never used for advertising or promotion. type: response client: taskd 1.0.0 protocol: v1 code: 200 status: Ok message: Scheduled maintenance 2013-07-14 08:00UTC for 10 minutes. 45da7110-1bcc-4318-d33e-12267a774e0f Note that the same message will likely be included in consecutive responses. ## Reference Implementation The Taskserver 1.1.0 codebase contains a reference implementation of an SSL/TLS client and server program, which communicate text strings. taskd.git/src/tls/Makefile # To build the example taskd.git/src/tls/README # How to run the example taskd.git/src/tls/TLSClient.cpp # TLS client code taskd.git/src/tls/TLSClient.h taskd.git/src/tls/TLSServer.cpp # TLS Server code taskd.git/src/tls/TLSServer.h taskd.git/src/tls/c.cpp # Client program taskd.git/src/tls/s.cpp # Server program taskd.git/src/tls/text.cpp # Text manipulation taskd.git/src/tls/text.h # Text manipulation The Taskwarrior codebase, version 2.4.0, is the reference implementation. task.git/src/TLSClient.cpp # TLS client code task.git/src/TLSClient.h task.git/src/commands/CmdSync.cpp # Sync implementation task.git/src/commands/CmdSync.h ## 2. Official Technical Reference & Guides (GothenburgBitFactory/tw.org) ## File: README.md # taskwarrior.org Site Repository This repository contains the content of [taskwarrior.org](https://taskwarrior.org), the website for the [Taskwarrior](https://github.com/GothenburgBitFactory/taskwarrior) project. ## Contributing To clone this repository, run ```shell git clone https://github.com/GothenburgBitFactory/tw.org ``` For minor changes, it is perfectly fine to simply change the relevant Markdown files and make a pull request. For more complex changes, here is how to build the documentation locally: 1. Install [hugo](https://gohugo.io/getting-started/quick-start/). 2. Run ```shell hugo server -D -w ``` This defaults to running a web server on `http://localhost:1313`. If you are running on an external host, try ```shell hugo server -D -w --bind 0.0.0.0 -b http:// ``` ## Updating Taskwarrior Versions To record a new release of Taskwarrior, run `bin/tw-release vX.Y.Z` and make a PR for the result. --- ## File: content/docs/commands/_get.md --- title: "Taskwarrior - _get" --- # _get The `_get` command is a [DOM](../../dom/) accessor. You can use this command to extract any piece of information stored by taskwarrior. For example to obtain the description of task 12: $ task _get 12.description Buy some milk You can specify multiple data items: $ task _get 12.description 12.project Buy some milk Kitchen You can use UUIDs: $ task _get a360fc44-315c-4366-b70c-ea7e7520b749.description Buy some milk The `_get` command makes it easy to map between ID and UUID: $ task _get 12.uuid a360fc44-315c-4366-b70c-ea7e7520b749 $ task _get a360fc44-315c-4366-b70c-ea7e7520b749.id 12 The `_get` command is a helper command, which means it is more useful for scripts and extensions than command line use. See Also - [DOM](../../dom/) - [`export`](../export/) command --- ## File: content/docs/commands/_index.md --- title: "Taskwarrior - What's next?" layout: single --- # Commands ## Commands Here are the commands alphabetically. Version-specific features are labelled with the version in which they were first available. * [`add` - Add a new task](add/) * `annotate` - Add an annotation to a task * [`append` - Append words to a task description](append/) * [`calc` {{< label >}}2.4.0{{< /label >}} - Expression calculator](calc/) * `config` - Modify configuration settings * `context` - Manage contexts * [`count` - Count the tasks matching a filter](count/) * `delete` - Mark a task as deleted * `denotate` - Remove an annotation from a task * [`done` - Complete a task](done/) * `duplicate` - Clone an existing task * `edit` - Launch your text editor to modify a task * `execute` - Execute an external command * [`export` - Export tasks in JSON format](export/) * `help` - Show high-level help, a cheat-sheet * `import` - Import tasks in JSON form * [`log` - Record an already-completed task](log/) * `logo` - Show the Taskwarrior logo * [`modify` - Modify one or more tasks](modify/) * [`prepend` - Prepend words to a task description](prepend/) * `purge` {{< label >}}2.6.0{{< /label >}} - Completely removes tasks, rather than change status to `deleted` * `start` - Start working on a task, make active * `stop` - Stop working on a task, no longer active * [`synchronize` - Syncs tasks with other instances](synchronize/) * `undo` - Revert last change * `version` - Version details and copyright ## Customizable Reports [Customizable reports](../report/) can be modified to suit your needs. They all work in same manner, and mostly differ by the [columns](columns/) shown, the [filter](../filter/) applied, and the sorting performed. Because all the customizable reports work in the same way, [the `list` report](list/) is the only report discussed. * `active` - Started tasks * `all` - Pending, completed and deleted tasks * `blocked` - Tasks that are blocked by other tasks * `blocking` - Tasks that block other tasks * `completed` - Tasks that have been completed * [`list` - Pending tasks](list/) * `long` - Pending tasks, long form * `ls` - Pending tasks, short form * `minimal` - Pending tasks, minimal form * `newest` - Most recent pending tasks * `next` - Most urgent tasks * `oldest` - Oldest pending tasks * `overdue` - Overdue tasks * `ready` - Pending, unblocked, scheduled tasks * `recurring` - Pending recurring tasks * `unblocked` - Tasks that are not blocked * `waiting` - Hidden, waiting tasks ## Fixed Reports The fixed reports have minimal customization, typically only color. * [`burndown.daily` - Burndown chart, by day](burndown/) * [`burndown.monthly` - Burndown chart, by month](burndown/) * [`burndown.weekly` - Burndown chart, by week](burndown/) * `calendar` - Calendar and holidays * `colors` - Demonstrates all supported colors * [`columns` - List of report columns and supported formats](columns/) * `commands` {{< label >}}2.5.0{{< /label >}} - List of commands, with their behaviors * `diagnostics` - Show diagnostics, for troubleshooting * `ghistory.annual` - History graph, by year * `ghistory.monthly` - History graph, by month * `ghistory.weekly` {{< label >}}2.6.0{{< /label >}} - History graph, by week * `ghistory.daily` {{< label >}}2.6.0{{< /label >}} - History graph, by day * `history.annual` - History report, by year * `history.monthly` {{< label >}}2.6.0{{< /label >}} - History report, by month * `history.weekly` {{< label >}}2.6.0{{< /label >}} - History report, by week * `history.daily` - History report, by day * `ids` - Filtered list of task IDs * [`information` - All attributes shown](info/) * `projects` - Filtered list of projects, with task counts * `reports` - List of available reports * `show` - Filtered list of configuration settings * `stats` - Filtered statistics * `summary` - Filtered project summary * `tags` - Filtered list of tags * `timesheet` - Weekly timesheet report * `udas` - Details of all defined UDAs * `uuids` - Filtered list of UUIDs ## Helper Commands Helper commands all begin with an underscore, and they exist to provide support for third party add-ons, such as shell completion scripts. Helper commands generate no extraneous output, and are therefore easy to parse. Helper commands are not intended for regular use, but there is no reason for that to stop you. * `_aliases` - List of active aliases * `_columns` - List of supported columns * `_commands` - List of supported commands * `_config` - List of configuration setting names * `_context` - List of defined context names * [`_get` - DOM accessor](_get/) * `_ids` - Filtered list of task IDs * `_projects` - Filtered list of project names * `_show` - List of `name=value` configuration settings * `_tags` - Filtered list of tags in use * `_udas` - List of configured UDA names * [`_unique` - {{< label >}}2.5.0{{< /label >}} List of unique values for the specified attribute](_unique/) * `_urgency` - Filtered list of task urgencies * `_uuids` - Filtered list of pending UUIDs * `_version` - Task version (and optional git commit) * `_zshattributes` - Zsh formatted task attribute list * `_zshcommands` - Zsh formatted command list * `_zshids` - Zsh formatted ID list * `_zshuuids` - Zsh formatted UUID list --- ## File: content/docs/commands/_unique.md --- title: "Taskwarrior - _unique" --- # _unique The `_unique` command generates a filtered list of unique values for a given attribute. For example, to generate the list project names: ``` $ task _unique project Home Home.Garden Work ``` In addition to `project`, any attribute can be specified, for example, task `status`: ``` $ task _unique status pending deleted completed ``` There ## Filters You can specify a filter, to consider a subset of tasks, for example, here we see that the `Home.Garden` project has only pending tasks: ``` $ task project:Home.Garden _unique status pending ``` ## Limitations - Date attributes are presented in raw epoch form. This is a helper command, after all. ## See Also Other ways of generating unique lists include: - `_aliases` command - `_config` command - `_context` command - `_ids` command - `_projects` command - `_show` command - `_tags` command - `_udas` command - `_uuids` command --- ## File: content/docs/commands/add.md --- title: "Taskwarrior - Add Command" --- # add The `add` command is the primary means of creating tasks. The simplest task requires only a description: ``` $ task add Fix the leaky plumbing ``` You can enter the description as above, just by including the words as command line arguments. You can also provide quoted strings: ``` $ task add "Don't forget to shut off the main water valve first" ``` In this example the double-quotes hide the single unclosed quote in "Don't". You can also enter multi-line descriptions using quoted strings: ``` $ task add "Five syllables here Seven more syllables there Are you happy now?" ``` It is a good idea to quote task descriptions to avoid some problems with the shell, although not necessary. The (outer) quotes are not considered part of the description, in fact Taskwarrior never sees them because the shell removes them first. Dealing with shell issues is covered in detail in the [Escaping Shell Characters](#) page. ## Other Attributes In addition to a description, other attributes may be provided in the following manner: ``` $ task add Find the adjustable wrench project:Home priority:H ``` This example sets a project and a priority, to a new task. Note that the order of the words in the task description are preserved, but there is no need to put the project and priority at the end of the command - they may appear anywhere on the line. Here are two equivalent commands to illustrate this: ``` $ task add Find the project:Home adjustable priority:H wrench $ task add project:Home priority:H Find the adjustable wrench ``` In addition to project and priority, you may set the entry timestamp, start timestamp, due date, tags, recurrence frequency, until date, and status. You cannot add annotations while creating a task because it interferes with the task description. You may specify anything else except the ID and UUID. These are created automatically. ## Limitations - There is no way to simultaneously add a task and annotate it. Annotations must be applied to existing tasks. ## See Also Other ways of creating tasks include: - [`log`](../log/) command - `duplicate` command - `import` command --- ## File: content/docs/commands/append.md --- title: "Taskwarrior - Append Command" --- # append The `append` command is a way to add words to the end of a task description: ``` $ task add Fix plumbing $ task 1 append before the house floods ``` While adding words to the end of the description, the `append` command can also update other attributes: ``` $ task 1 append and before winter project:Home +repair $ task 1 list ID Age Project Tags Description Urg -- ---- ------- ------ ------------------------------------------------------ ---- 1 4min Home repair Fix plumbing before the house floods and before winter 1.8 ``` ## See Also Other ways of modifying task descriptions include: - [`modify`](../modify/) command - [`prepend`](../prepend/) command --- ## File: content/docs/commands/burndown.md --- title: "Taskwarrior - Burndown Command" --- # burndown.weekly (or .daily or .monthly) The `burndown` command shows a chart that depicts the number of pending, active and completed tasks over different time periods. This report makes it easy to gauge progress on a project, if a project is specified in the filter. With a filter, you can see the chart for any set of tasks. ## Alias There is an alias specified, by default, named `burndown` that expands to `burndown.weekly`. This could be overridden to show either `burndown.monthly` or `burndown.daily` reports instead. ## Convergence The `burndown` report tries to predict when the tasks matching the filter will all be completed. With version {{< label >}}2.5.1{{< /label >}} the following approach is used: The filtered tasks are scanned to see if a peak number of pending tasks exists. If the peak number of pending tasks is any time in the last three days, then more tasks are being added than are being completed. In this case, it is not possible to predict when that will change, and therefore when the tasks will all be completed. In the case where a peak has occurred more than three days ago, and the number of pending tasks has been dropping since, a *net fix rate* can be determined, which is the average number of tasks completed per day. This rate is shown on the chart. If a *net fix rate* is known, then it can be determined how long it might take to complete all the remaining matching tasks. This duration is added to the current date, and a predicted completion date can be calculated. This date is shown on the chart. This approach is based on a common pattern, which is that projects tend to move from a planning phase to an execution phase. This simply means that tasks tend to be created earlier in the process, and completed later in the process. This tends to create a peak number of pending tasks. With the convergence date based on a recent completion rate and count, the estimated completion date is just an estimate, and it's accuracy is unknown, but is related to consistency in the size of tasks, consistency in your time spent completing tasks. A more sophisticated approach such as [Evidence-Based Scheduling](https://www.joelonsoftware.com/2007/10/26/evidence-based-scheduling/) (EBS) would take into consideration estimates, actual time, and your task history. In earlier releases, the convergence algorithm tried too hard and got it wrong too often. Let's not mention that. ## See Also Related topics include: - `history` command --- ## File: content/docs/commands/calc.md --- title: "Taskwarrior - Calc Command" --- # calc Taskwarrior has a `calc` command that exposes the algebraic expression evaluator used by all other commands and filters. This is handy for quick calculations from the command line, but combined with DOM access, can be very useful. ## Numbers This can be used to perform basic mathematics using the `+`, `-`, `*` and `/` operators: ``` $ task calc 1+2*3 7 ``` In the above example, care was taken to not allow that `*` operator to be expanded by the shell into a list of file in the current directory. The best solution to this is to simply quote the expression. In addition to integers, you can use real numbers and scientific notation: $ task calc '1.23e-4.5 ^ 2' 1.5129e-8 In addition to exponentiation, `^`, there is the `%` modulus operator. ## Boolean The `and`, `or`, `xor`, `==`, `!==`, `=`, `!=`, `!`, `~`, `!~`, `<=`, `<`, `>=`, and `>` operators allow Boolean expressions: ``` $ task calc true and false false $ calc true or false true $ calc true xor true false $ calc '1 < 2 and -1 < 0' true ``` A number can be converted to a Boolean value with a double negative: ``` $ task calc '!!3' true ``` Otherwise, type conversions are automatic. ## Text Text, or strings, can be manipulated in more limited ways, for example there is concatenation: ``` $ task calc foo + bar foobar ``` Multiplication is supported in the form of replication: ``` $ task calc 'x * 40' xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` There is support for regular expressions, using the `~` match and `!~` no-match operator: ``` $ task calc 'foo ~ f' true $ task calc 'foo !~ z' true $ task calc '"The quick brown fox" ~ "q"' true ``` Again, you'll need to protect the `~` and `!~` characters from interpretation by the shell, and in the last example, to protect the spaces in the sentence. ## Dates With date support, basic date synonyms like `now`, `today`, `yesterday` and `tomorrow` are supported: ``` $ task calc now 2014-06-28T12:44:07 $ task calc today 2014-06-28T00:00:00 ``` Dates can be added, subtracted and compared, and combined with durations: ``` $ task calc tomorrow + 2 weeks - 1d 2014-07-12T00:00:00 ``` The expression evaluator understand ISO-8601 date formats, and in fact supports over 40 of them. For example when does week 40 start in 2014? ``` $ task calc 2014W40 2014-09-28T00:00:00 ``` When is the FIFA World Cup final, which starts at 4pm in Brasil local time, shown in the EST (local) time zone? ``` $ task calc 2014-07-13T16:00:00-03:00 2014-07-13T15:00:00 ``` ## Durations A duration is either the difference between dates, or a specified interval. Durations can be summed: ``` $ task calc 12h + 25m +30s PT12H25mPT30S ``` Subtracting dates yields a duration, here answering the question of how much time is there between the end of this month (June 2014) and the end of the year: ``` $ task calc eoy-eom P184DT1H ``` Note that the '1H' corresponds to the extra hour gained when summer time ends. When does the 32-bit `time_t` problem (Unix Epoch, Y2K38) arrive? ``` $ task calc later-now P23Y209DT11H55M11S ``` Looks like we have 23 years to deal with that. More importantly though, how long until the FIFA World Cup final? $ task calc 2014-07-13T15:00:00-03:00 - now P15DT1H11M46S Durations are shown using the ISO-8601 designated format, using only precise units, that is, not in years or months. ## DOM Access The expression evaluator has access to the Taskwarrior DOM, which is a complete source of task information. This information can be accessed and used in an expression using regular Taskwarrior DOM references: ``` $ task calc '1.urgency > 2.urgency' false ``` Because of DOM access, the `calc` command can mimic the `_get` helper command. In what year did I enter task 100? ``` $ task calc 100.entry.year 2012 ``` What week was that? ``` $ task calc 100.entry.week 30 ``` ## Calc Utility Taskwarrior has a standalone `calc` utility that has the same features, except for DOM access. This utility is used for testing, but has a few interesting features of its own. ## Calc Postfix Internally, the expression evaluator converts infix expressions (1 + 2 * 3) to postfix (1 2 3 * +), which is easier to implement and optimize, but `calc` exposes this: ``` $ calc --postfix '1 2 3 * +' 7 ``` ## Calc Debugging There is also support for a `--debug` command line option, which displays the stack operations as the expression is evaluated in postfix form. ``` $ calc --postfix --debug '1 2 3 * +' [0] eval push '1' [1] eval push '2' [2] eval push '3' [3] eval pop '3' [2] eval pop '2' [1] eval operator '*' [1] eval result push '6' [2] eval pop '6' [1] eval pop '1' [0] eval operator '+' [0] eval result push '7' 7 ``` You can see that the processing begins by pushing the three values on to the stack, then two are popped when the `*` binary operator is encountered. The two value are multiplied, and the result, 6 is pushed back. Next the `+` binary operator is encountered, which pops two values off the stack, the sum, 7, is pushed back. The number in brackets is the stack size before the operation is performed. If there is a problem found with the Taskwarrior expression evaluator, it can be verified and tested in this way, using the `calc` utility. --- ## File: content/docs/commands/columns.md --- title: "Taskwarrior - Columns Command" --- # columns The `columns` command shows a list of all the supported columns available for inclusion in a custom report. Each column may have multiple formats, and there are examples shown of each of those formats. As an example, a `due` date can be shown in various ways. It can be formatted according to the `dateformat` configuration setting. It can also be shown as a Julian date, a POSIX epoch, in ISO-8601 format, as an 'age' value or as a 'countdown' value. Each column has a default format, so if the custom report specifies: ``` report.my_list.columns=...,due,... ``` Then the default format is used. Other formats can be used like this: ``` report.my_list.columns=...,due.iso,... ``` Here is sample output for the `columns` command: ``` /* Detailed source-code truncated for AI context efficiency. */ ``` --- ## File: content/docs/commands/count.md --- title: "Taskwarrior - Count Command" --- # count The `count` command simply counts tasks: ``` $ task count 249 ``` By default, all tasks are counted, which includes completed, deleted and pending. If you want to count just the pending tasks, add a filter: ``` $ task status:pending count 32 ``` If a [context](../../context/) is active, the `count` command obeys it. ## See Also Other ways of counting tasks include: - [`_unique`](../_unique/) command