### Display Help for Timewarrior Commands

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-help.1.adoc

Use this command to get specific help for Timewarrior commands. For example, to understand the 'start' command, use 'timew help start'.

```bash
$ timew help start
```

--------------------------------

### Command `start`

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/rfc_command_definition.md

Starts a new time tracking interval.

```APIDOC
## Command `start`

### Description

Starts a new time tracking interval. If an interval is already active, it will be closed and a new one opened if the tags differ.

### Method

N/A (CLI Command)

### Endpoint

N/A (CLI Command)

### Arguments

* `date` (optional): The date and time to start the interval. Defaults to the current time.
* `tags` (optional): A list of one or more tags to associate with the interval.

### Behavior

* If no time tracking is active, creates a new open interval.
* If time tracking is active, closes the current interval and opens a new one only if the provided tags differ from the current interval's tags.

### Synopsis

```bash
timew start [<date>] [<tags>]
```

### Request Example

```bash
timew start 10:00:00
timew start 2023-10-27T09:00:00 project-x
```

### Response

N/A (CLI Command)
```

--------------------------------

### Timewarrior Interval Examples

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man7/timew-ranges.7.adoc

These examples demonstrate the flexible syntax for defining time intervals in Timewarrior. They cover specifying start and end times, durations, and relative times.

```shell
from 9:00
```

```shell
from 9am - 11am
```

```shell
from 9:00:00 to 11:00
```

```shell
from 9:00 for 2h
```

```shell
2h after 9am
```

```shell
2h before 11:00
```

```shell
2h ago
```

```shell
for 2h
```

--------------------------------

### Start Time Tracking with Date and Tags

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-start.1.adoc

Specify an optional start time along with tags to begin tracking. If a previous interval is open, it will be closed at this specified start time.

```bash
$ timew start 8am weekend 'Home & Garden'
```

--------------------------------

### Start Command Synopsis

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/rfc_command_definition.md

Defines the synopsis for the 'start' command, which can optionally take a date and tags.

```bash
timew start [<date>] [<tags>]
```

--------------------------------

### Install Timewarrior

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/README.md

Install Timewarrior to the system. This command typically requires sudo privileges unless a custom install prefix is used.

```bash
sudo cmake --install _build
```

--------------------------------

### Install Timewarrior Themes

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/themes/CMakeLists.txt

Use this CMake script to install theme files to the specified directory.

```cmake
cmake_minimum_required (VERSION 3.10)

message ("-- Configuring theme documentation")

install (FILES README           DESTINATION ${TIMEW_DOCDIR}/themes)
install (FILES dark.theme       DESTINATION ${TIMEW_DOCDIR}/themes)
install (FILES dark_blue.theme  DESTINATION ${TIMEW_DOCDIR}/themes)
install (FILES dark_green.theme DESTINATION ${TIMEW_DOCDIR}/themes)
install (FILES dark_red.theme   DESTINATION ${TIMEW_DOCDIR}/themes)
```

--------------------------------

### Install Timewarrior Extensions

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/ext/CMakeLists.txt

Installs Timewarrior extension files like 'on-modify.timewarrior' and 'totals.py' to the documentation directory. Ensure TIMEW_DOCDIR is correctly set.

```cmake
cmake_minimum_required (VERSION 3.10)

message ("-- Configuring extensions")

install (FILES on-modify.timewarrior totals.py DESTINATION ${TIMEW_DOCDIR}/ext)
```

--------------------------------

### Install Timewarrior with Custom Prefix

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/README.md

Install Timewarrior to a custom location by specifying CMAKE_INSTALL_PREFIX during the CMake configuration step.

```bash
cmake -DCMAKE_BUILD_TYPE=release -DCMAKE_INSTALL_PREFIX=/path/to/your/install/location -S . -B _build
```

--------------------------------

### Start Time Tracking with Tags

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-start.1.adoc

Use this command to begin tracking time with specified tags. Multi-word tags must be enclosed in quotes.

```bash
$ timew start weekend 'Home & Garden'
```

--------------------------------

### TimeWarrior Hint Example

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/rfc_command_definition.md

Demonstrates the usage of hints to modify command behavior, using the ':quiet' hint.

```bash
:quiet
```

--------------------------------

### Bug Report Reproduction Example

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/CONTRIBUTING.md

An example format for describing a bug, detailing the steps to reproduce it and the expected versus actual output. This helps in clearly communicating issues.

```text
When I do this
And I do that
And I call "timew command"
Then I should get "FOO"
But the actual output is "BAR"
```

--------------------------------

### TimeWarrior Range Examples

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/rfc_command_definition.md

Illustrates how to specify time ranges using date differences or a date and duration.

```bash
09:45 - 11:15
```

```bash
two hours before 10:45
```

```bash
30mins until 2017-03-23T13:13
```

```bash
one hour ago
```

--------------------------------

### TimeWarrior Subcommand Example

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/rfc_command_definition.md

Demonstrates the use of subcommands to specify command behavior, shown with the 'tag' command.

```bash
timew tag list
```

```bash
timew tag remove @3 foo bar
```

--------------------------------

### ISO Datetime Examples

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man7/timew-dates.7.adoc

Examples of extended and standard ISO datetime formats supported by Timewarrior. Times followed by 'Z' are UTC; otherwise, local time is assumed.

```text
2016-06-09T08:12:00Z
```

```text
2016-06T08:12:00+01:00
```

```text
2016-06T08:12Z
```

```text
2016-161
```

```text
2016-W244
```

```text
2016-W24
```

```text
20160609T081200Z
```

```text
2016W24
```

```text
8:12:00Z
```

```text
0812-0500
```

--------------------------------

### Display Help for Timewarrior Hints

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-help.1.adoc

Use this command to get specific help regarding the hints feature in Timewarrior. This explains how to use hints for better time tracking.

```bash
$ timew help hints
```

--------------------------------

### Get Python Version

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/CONTRIBUTING.md

This command is used to find out the installed Python version, which may be necessary information for bug reports.

```bash
python --version
```

--------------------------------

### Short Time Format Examples

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man7/timew-dates.7.adoc

Examples of short time formats recognized by Timewarrior. These can be used independently or as part of a datetime.

```text
8am
```

```text
24th
```

```text
monday
```

```text
august
```

--------------------------------

### Import Intervals from a Single File

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-import.1.adoc

Import intervals from a single JSON file. File paths not starting with '/' are relative to the current directory.

```bash
timew import intervals.json
```

--------------------------------

### Named Date and Time Examples

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man7/timew-dates.7.adoc

Examples of named dates and times supported by Timewarrior for convenience. These often default to midnight (0:00:00) unless otherwise specified.

```text
now
```

```text
today
```

```text
yesterday
```

```text
tomorrow
```

```text
<day-of-week>
```

```text
<month-of-year>
```

```text
hh:mm[:ss][am|a|pm|p]
```

```text
Nst, Nnd, Nrd, Nth
```

```text
<epoch>
```

```text
later
```

```text
someday
```

```text
sopd, eopd
```

```text
sod, eod
```

```text
sond, eond
```

```text
sopw, eopw
```

```text
sow, eow
```

```text
sonw, eonw
```

```text
sopww, eopww
```

```text
soww, eoww
```

```text
sonww, eonww
```

```text
sopm, eopm
```

```text
som, eom
```

```text
sonm, eonm
```

```text
sopq, eopq
```

```text
soq, eoq
```

```text
sonq, eonq
```

```text
sopy, eopy
```

```text
soy, eoy
```

```text
sony, eony
```

```text
easter
```

```text
eastermonday
```

```text
ascension
```

```text
pentecost
```

```text
goodfriday
```

```text
midsommar
```

```text
midsommarafton
```

```text
juhannus
```

--------------------------------

### Display Help for Timewarrior Interval Syntax

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-help.1.adoc

Use this command to get specific help on the interval syntax used in Timewarrior. This is crucial for correctly logging time entries.

```bash
$ timew help interval
```

--------------------------------

### Display Help for Timewarrior DOM References

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-help.1.adoc

Use this command to get specific help regarding DOM references within Timewarrior. This is useful for advanced users or integration purposes.

```bash
$ timew help dom
```

--------------------------------

### Run Performance Tests (Local)

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/test/performance/README.md

Execute performance tests locally. Ensure Timewarrior is in your PATH and Hyperfine version 1.19.0 or newer is installed. An optional output directory can be specified.

```bash
# Run tests (default output: ./performance-test/output)
./performance-test.sh [output_directory]
```

--------------------------------

### Defining Hints for Commands

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/rules.txt

Augment built-in hints used by commands. This example shows hints for the 'staff' tag, suggesting related tags.

```timewarrior-rules
define hints:
  staff:
    tag 'Staff Meeting'
    tag 'Admin'
```

--------------------------------

### TimeWarrior Date Formats

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/rfc_command_definition.md

Provides examples of various formats for specifying dates in TimeWarrior commands.

```bash
1pm
```

```bash
10:33
```

```bash
2017-04-11T17:12:23
```

```bash
now
```

--------------------------------

### Continue tracking an interval via a tag set

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-continue.1.adoc

You can resume tracking by providing a set of tags. The command will use the first interval matching these tags as a blueprint for the new open interval, starting at the current time. Note that if multiple intervals match, the first one found is used, not necessarily the most specific match.

```bash
$ timew continue FOO BAR
```

--------------------------------

### Continue tracking an interval at a specific time

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-continue.1.adoc

To resume tracking at a specific time, provide the interval identifier (ID or tags) followed by the desired start time. This creates a new open interval starting at the specified time.

```bash
$ timew continue @4 19:00
```

```bash
$ timew continue FOO 19:00
```

--------------------------------

### Display Help for Timewarrior Date Formats

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-help.1.adoc

Use this command to get specific help on the date formats supported by Timewarrior. This ensures accurate date entries.

```bash
$ timew help date
```

--------------------------------

### Record a Closed Interval with timew-track

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-track.1.adoc

Use this command to record a past time interval with a start and end time. If a closed interval is not provided, it behaves like the 'start' command.

```bash
$ timew track :yesterday 'Training Course'
```

```bash
$ timew track 9am - 11am 'Staff Meeting'
```

--------------------------------

### timew track

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/rfc_command_definition.md

The `track` command is a shortcut to start a new interval and stop it at a specified time, optionally with tags.

```APIDOC
## timew track <range> [<tags>]

### Description
Tracks a time interval by starting a new interval and stopping it at a specified end date. This is a shortcut for `timew start` followed by `timew stop`.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* `range` (string) - Required - The date range in the format `<start-date> - <stop-date>`.
* `tags` (string) - Optional - A list of one or more tags.

### Request Example
timew track 2023-01-01 - 2023-01-02 "Work Project A"

### Response
#### Success Response (200)
No explicit output on success, operation is performed.

#### Response Example
(No output)
```

--------------------------------

### Defining General Rules for Constraints

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/rules.txt

Create rules to enforce constraints on data. This example prevents the value 'foo' from exceeding 3 for 'tag1'.

```timewarrior-rules
define rules:
  one:
    tagset = tag1
    if foo > 3:
      error "The value of 'foo' may not exceed 3."
```

--------------------------------

### Resize Multiple Intervals with timew-resize

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-resize.1.adoc

Allows resizing of multiple intervals simultaneously by listing their IDs followed by the desired duration. This example resizes intervals '@3', '@1', and '@13' to 1 hour.

```bash
$ timew resize @3 @1 @13 1hour
```

--------------------------------

### Move Interval to New Start Time with timew move

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-move.1.adoc

After identifying the interval ID (e.g., '@2'), use this command to change its start time to a new specified time (e.g., '9am').

```bash
$ timew move @2 9am
```

--------------------------------

### Display Help for Timewarrior Duration Formats

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-help.1.adoc

Use this command to get specific help on the duration formats supported by Timewarrior. This is important for specifying time spans correctly.

```bash
$ timew help duration
```

--------------------------------

### Join Two Intervals with timew-join

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-join.1.adoc

Execute the 'timew join' command with the IDs of the two intervals you wish to merge. The command will combine them based on their start and end times and tags.

```bash
$ timew join @1 @2
```

--------------------------------

### Set Timewarrior Configuration Value

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-config.1.adoc

Use this command to set a specific configuration option to a desired value. For example, to enable verbose logging, set 'verbose' to 'yes'.

```bash
$ timew config verbose yes
```

--------------------------------

### Timewarrior Date Range Exclusion Example

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man7/timew-dates.7.adoc

Demonstrates how using 'today' as an upper range limit excludes intervals from the current day. Use 'now' or 'tomorrow' to include the current day.

```bash
$ timew sum 2d before today
```

```bash
$ timew sum 2d before now
```

```bash
$ timew sum 2d before tomorrow
```

--------------------------------

### Export All Tracked Intervals in JSON

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-export.1.adoc

Exports all tracked intervals in JSON format. The output is sorted by start time, with the oldest interval first. This command is useful for backing up or analyzing all your time data.

```bash
$ timew export
[
{"id":2,"start":"20231001T103000Z","end":"20231001T120000Z","tags":["work"],"annotation":"Project work"},
{"id":1,"start":"20231001T090000Z","end":"20231001T100000Z","tags":["work"],"annotation":"Morning meeting"},
]

```

--------------------------------

### Fill Gap Between Intervals with timew-track

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-track.1.adoc

Utilize the ':fill' hint to create a new interval that automatically adjusts to fill the gap between two adjacent recorded intervals. This avoids the need to specify exact start and end times for the new interval.

```bash
$ timew track 10:00 - 11:00 :fill 'Coffee Break'
```

--------------------------------

### Add tags to the current active interval

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-tag.1.adoc

If time tracking is active, tags can be added to the current open interval by omitting the interval ID. This example first starts a new interval 'foo' and then tags the active interval with 'bar'.

```bash
$ timew start foo
$ timew tag bar
```

--------------------------------

### Weekly Summary Report

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/report.summary.txt

Displays a detailed weekly summary of tracked time, broken down by day and including individual entries with start and end times. Use this to review daily activities and total time spent.

```bash
$ timew summary :week
```

```text
Wk  Date       Day Tags               Start End   Time  Sub
--- ---------- --- ------------------ ----- ----- ----- -----
W17 2016-04-25 Mon Holiday
W17 2016-04-26 Tue Research, B23       9:00 12:30  3:30
                   Research, B23      13:30 18:00  4:30  8:00
W17 2016-04-27 Wed Training Security   9:00 12:00  3:00
                   Training Privacy   13:00 17:00  4:00  7:00
W17 2016-04-28 Thu Staff Meeting       8:45 10:30  1:45
                   Research, A44      10:40 12:00  1:20
                   Research, A44      12:45 17:52  5:07  8:12
W17 2016-04-29 Fri Research, C17       8:41 12:00  3:19
                   Dept Meeting       13:00 14:30  1:30
                   Planning           14:30 15:30  1:00
                   Research, C17      15:30 17:40  2:10  7:59
--- ---------- --- ------------------ ----- ----- ----- -----
                   Total                                31:11
```

--------------------------------

### timew-join

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-join.1.adoc

Joins two specified intervals into a single interval. The new interval will have the earlier start time and the later end time of the two original intervals, along with a combined set of tags.

```APIDOC
## POST /timew/join

### Description
Joins two intervals, using the earlier one of the two start times, and the later one of the two end times, and the combined set of tags.

### Method
POST

### Endpoint
/timew/join

### Parameters
#### Path Parameters
- **id1** (integer) - Required - The ID of the first interval to join.
- **id2** (integer) - Required - The ID of the second interval to join.

### Request Example
```json
{
  "id1": "@1",
  "id2": "@2"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the intervals were joined.

#### Response Example
```json
{
  "message": "Intervals @1 and @2 have been successfully joined."
}
```
```

--------------------------------

### Display General Help in Timewarrior

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-help.1.adoc

Use this command to view the general help information for Timewarrior. This is the entry point for understanding the tool's capabilities.

```bash
$ timew help
```

--------------------------------

### Modify the start date of an interval

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-modify.1.adoc

Use this command to set a new start date and time for a specified interval ID. Ensure the new start time is not after the interval's end time.

```bash
timew modify start @3 2020-12-28T17:00
```

--------------------------------

### Configure Files for Execution

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/test/CMakeLists.txt

Copies necessary files for execution and documentation generation. This ensures that runtime scripts and documentation are available.

```cmake
configure_file(run_all run_all COPYONLY)
configure_file(problems problems COPYONLY)
```

--------------------------------

### Display All Timewarrior Configuration Settings

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-config.1.adoc

When no arguments are provided, the 'timew config' command displays all currently active configuration settings and their values.

```bash
$ timew config
verbose = yes
...
```

--------------------------------

### Basic TimeWarrior Usage

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/rfc_command_definition.md

Illustrates the fundamental structure for invoking TimeWarrior commands, including version, help, and general command execution.

```bash
timew [--version | --help | <command> [<args>]]
```

--------------------------------

### timew-move

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-move.1.adoc

Changes the start time of a specified interval.

```APIDOC
## POST /timew/move

### Description
Changes the start time of a specified interval.

### Method
POST

### Endpoint
/timew/move

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the interval to move. Use `timew summary :ids` to find interval IDs.
- **date** (string) - Required - The new start time for the interval (e.g., '9am', '14:30').

### Request Example
```json
{
  "id": "@2",
  "date": "9am"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the interval was moved.

#### Response Example
```json
{
  "message": "Interval @2 moved to 9am."
}
```
```

--------------------------------

### Import Intervals from Multiple Files

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-import.1.adoc

Import intervals from multiple JSON files using shell wildcards or absolute paths.

```bash
timew import /path/to/intervals/*.json
```

--------------------------------

### Continue tracking an interval within a specific range

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-continue.1.adoc

To resume tracking and immediately close the interval, specify the interval identifier (ID or tags) followed by a start and end time. This creates a new closed interval with the specified start and end times.

```bash
$ timew continue @4 19:00 - 20:00
```

```bash
$ timew continue FOO 19:00 - 20:00
```

--------------------------------

### Checkout Development Branch

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/CONTRIBUTING.md

Before making changes, ensure you are on the 'develop' branch, which is the main branch for development.

```bash
git checkout dev
```

--------------------------------

### Get Timewarrior Version

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/CONTRIBUTING.md

Use this command to retrieve the current version of Timewarrior, which is often required when submitting bug reports.

```bash
timew --version
```

--------------------------------

### Show interval IDs

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-continue.1.adoc

Use the 'summary' command with the ':ids' hint to display interval IDs, which can then be used with 'timew-continue'.

```bash
$ src/timew summary :ids

Wk  Date       Day ID Tags             Start      End    Time   Total
W23 2020-06-04 Thu @4 BAR           13:00:00 14:00:00 1:00:00
                   @3 BAR, FOO      14:00:00 15:00:00 1:00:00
                   @2 BAR, BAZ, FOO 15:00:00 16:00:00 1:00:00
                   @1 FOO           16:00:00 17:00:00 1:00:00 4:00:00

                                                                  4:00:00
```

--------------------------------

### CMake Minimum Version and Project Configuration

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/CMakeLists.txt

Sets the minimum required CMake version and configures project-wide settings. Includes messages for build progress.

```cmake
cmake_minimum_required (VERSION 3.10)

message ("-- Configuring documentation")
```

--------------------------------

### Modify the range of an interval

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-modify.1.adoc

Change both the start and end times of an interval in a single command. The date can be omitted if the interval is for the current day.

```bash
timew modify range @3 2020-12-28T17:00 - 2020-12-28T18:00
```

--------------------------------

### Include Documentation Subdirectories

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/CMakeLists.txt

Includes subdirectories for man page documentation (man1 and man7). These are essential for generating the project's manual pages.

```cmake
add_subdirectory (man1)
add_subdirectory (man7)
```

--------------------------------

### Defining Exclusions in Timewarrior

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/rules.txt

Define time periods during which tracking should be excluded. This example shows daily exclusions and specific date overrides.

```timewarrior-rules
define exclusions:
  monday    = <8:00:00 12:00:00-12:45:00 >17:30:00
  tuesday   = <8:00:00 12:00:00-12:45:00 >18:30:00
  wednesday = <8:00 12:00-13:30 >17:30
  thursday  = <8:00 12:00-12:45 >17:30
  friday    = <8:00 12:00-12:45 >17:30

  days:
    2016_01_01 = Working
    2016_01_02 = Off
```

--------------------------------

### Run an extension report with a range

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-report.1.adoc

This command runs an extension report named 'foo' for the current week. The 'report' keyword is optional.

```bash
$ timew report foo :week
```

```bash
$ timew        foo :week
```

--------------------------------

### timew-show - Display Configuration

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-show.1.adoc

The `timew-show` command displays the effective configuration of Timewarrior in a hierarchical format.

```APIDOC
## timew show

### Description
Displays the effective configuration in hierarchical form.

### Method
N/A (Command-line tool)

### Endpoint
N/A (Command-line tool)

### Parameters
N/A

### Request Example
```bash
timew show
```

### Response
#### Success Response
Displays the effective configuration.

#### Response Example
(Output will vary based on user configuration)
```

--------------------------------

### Executable and Library Linking for Tests

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/test/CMakeLists.txt

Configures individual test executables, linking them with the main Timewarrior library and other necessary components. This prepares each test for compilation and execution.

```cmake
foreach (src_FILE ${timew_test_SRCS})
  add_executable (${src_FILE} "${src_FILE}.cpp" test.cpp)
  target_link_libraries (${src_FILE} timew shared ${timew_test_LIBS})
endforeach (src_FILE)
```

--------------------------------

### Resize a Single Interval with timew-resize

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-resize.1.adoc

Resizes a specific interval identified by its ID to a new duration. For example, resizing interval '@3' to 15 minutes.

```bash
$ timew resize @3 15mins
```

--------------------------------

### Remove a specific tag from an interval

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-untag.1.adoc

Untag a specific interval by providing its ID and the tag name to be removed. For example, to remove 'Old Tag' from interval '@2'.

```bash
$ timew untag @2 'Old Tag'
```

--------------------------------

### Import Intervals from Standard Input

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-import.1.adoc

Import intervals from standard input, often used for synchronizing data between machines. The data must be in JSON format.

```bash
timew export | ssh <server> 'timew import'
```

--------------------------------

### Asciidoc Options Configuration

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/CMakeLists.txt

Configures options for Asciidoc if it is found. These options are used for generating documentation, likely man pages.

```cmake
if (ASCIIDOCTOR_FOUND)
  set (ASCIIDOCTOR_OPTIONS "--attribute=manmanual=User Manuals"
                           "--attribute=mansource=timew ${PROJECT_VERSION}")
endif (ASCIIDOCTOR_FOUND)
```

--------------------------------

### Continue tracking without specifying an interval

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-continue.1.adoc

When no ID or tags are provided, 'timew-continue' resumes the first interval in the database, starting a new open interval at the current time.

```bash
$ timew continue
```

--------------------------------

### Weekly Summary Report (One Line per Day)

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/report.summary.txt

Presents a condensed weekly summary where each day is represented by a single line, aggregating tags and total time. Useful for a quick overview of daily accomplishments.

```bash
$ timew summary :week
```

```text
Wk  Date       Day Tags                                  Sub
--- ---------- --- ------------------------------------- -----
W17 2016-04-25 Mon Holiday
W17 2016-04-26 Tue Research, B23                          8:00
W17 2016-04-27 Wed Training Security, Training Privacy    7:00
W17 2016-04-28 Thu Staff Meeting, Research, A44           8:12
W17 2016-04-29 Fri Research, C17, Dept Meeting, Planning  7:59

                   Total                                 31:11
```

--------------------------------

### Force Color Output with Timewarrior

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man7/timew-hints.7.adoc

Use the ':color' hint to force color output, even when Timewarrior's output is not a terminal. This is useful with 'watch' for live updates.

```shell
timew :color day
```

```shell
watch -c timew :color day
```

--------------------------------

### Mockup Table Structure

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/report.summary.txt

A tabular representation of time entries, showing tags, descriptions, and durations. This format can be used for manual data entry or as a reference for report generation.

```text
Tag   Description Time    Total
----- ----------- ------- -------
Item1 Task one    1:00:00
      Task two    1:00:00
      Task three  0:30:00
                          2:30:00
Item2 Task one    2:30:00
      Task two    0:30:00
                          3:00:00
```

--------------------------------

### Display Week Chart with Tags

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-chart.1.adoc

Use the 'week' command with tags to filter the chart data. Multiple tags can be specified.

```bash
$ timew week FOO BAR
```

--------------------------------

### TimeWarrior Command Line Structure

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/rfc_command_definition.md

Shows the basic structure of a TimeWarrior command line, consisting of a command followed by words.

```bash
timew <words>
```

--------------------------------

### Defining Hook Rules for Events

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/rules.txt

Define rules that act as hooks for internal events like starting, stopping, or modifying time entries. These can trigger external scripts with arguments.

```timewarrior-rules
define rules:
  on_start:
    ...

define rules:
  on_stop:
    ...

define rules:
  on_modify:
    ...

define rules:
  on_modify:
    run /path/to/my/script <dom1> <dom2>
```

--------------------------------

### Run Performance Tests (Docker)

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/test/performance/README.md

Execute performance tests within a Docker container using the latest stable Timewarrior version. Specify directories for benchmark results and preloaded database entries.

```bash
./run-performance-test <output_dir> <database_dir>
```

--------------------------------

### Untag the current active interval

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-untag.1.adoc

If time is actively being tracked, you can omit the interval ID to remove tags from the current open interval. This example removes the 'bar' tag, leaving 'foo'.

```bash
$ timew start foo bar
$ timew untag bar
```

--------------------------------

### TimeWarrior CLI Usage

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/rfc_command_definition.md

General usage of the TimeWarrior command-line tool.

```APIDOC
## TimeWarrior CLI Usage

### Description

General usage of the TimeWarrior command-line tool.

### Method

N/A (CLI Tool)

### Endpoint

N/A (CLI Tool)

### Parameters

#### Path Parameters

N/A

#### Query Parameters

N/A

#### Request Body

N/A

### Request Example

```bash
timew [--version | --help | <command> [<args>]]
```

### Response

N/A (CLI Tool)
```

--------------------------------

### Debug Build Configuration with libfiu

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/test/CMakeLists.txt

Configures the build for debug mode, checking for and enabling the libfiu library if found. This allows for additional failure condition tests.

```cmake
if (uppercase_CMAKE_BUILD_TYPE MATCHES "DEBUG")
  find_library(FIU_ENABLE fiu) 
  if (FIU_ENABLE)
    message (STATUS "libfiu found")
    add_definitions (-DFIU_ENABLE)
    set (timew_test_LIBS fiu ${TIMEW_LIBRARIES})
  else (FIU_ENABLE)
    message (STATUS "NOTE: install libfiu to run additional tests")
    set (timew_test_LIBS ${TIMEW_LIBRARIES})
  endif (FIU_ENABLE)
else (uppercase_CMAKE_BUILD_TYPE MATCHES "DEBUG")
  set (timew_test_LIBS ${TIMEW_LIBRARIES})
endif (uppercase_CMAKE_BUILD_TYPE MATCHES "DEBUG")
```

--------------------------------

### Modify the end date of an interval

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-modify.1.adoc

Update the end date and time for an interval. If the interval is for the current day, the date portion can be omitted. The new end time must be after the interval's start time.

```bash
timew modify end @3 18:00
```

--------------------------------

### Displaying Time Warrior Summary After Filling

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-fill.1.adoc

Shows the updated time tracking summary after the 'timew fill' command has been applied. Observe how the selected interval '@2' has expanded to fill the gaps.

```bash
$ timew summary

Wk  Date       Day ID Tags    Start      End    Time   Total
--- ---------- --- -- ---- -------- -------- ------- -------
W32 2025-08-10 Sun @3 FOO   8:00:00  9:00:00 1:00:00
                   @2 BAR   9:00:00 12:00:00 3:00:00
                   @1 BAZ  12:00:00 13:00:00 1:00:00 5:00:00
                                                     -------
                                                     5:00:00
```

--------------------------------

### timew-modify - Change the range of an interval

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-modify.1.adoc

The 'modify' command allows you to alter the start date, end date, or the entire range of an existing interval. You can also use hints to automatically fill gaps or adjust for overlapping intervals.

```APIDOC
## timew-modify

### Description
Changes the range of a timewarrior interval.

### Method
CLI Command

### Endpoint
N/A (CLI tool)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
This command does not use a request body. It operates via command-line arguments.

### Command Syntax
`timew modify (start|end) <id> <date>`
`timew modify range <id> <range>`

### Parameters Explained
- **start|end**: Subcommand to specify whether to modify the start or end of the interval.
- **range**: Subcommand to modify the entire range of the interval.
- **<id>**: The unique identifier of the interval to be modified. Use `timew-summary(1)` to find interval IDs.
- **<date>**: The new date for the start or end of the interval. Can be omitted if the interval date is today.
- **<range>**: The new start and end times for the interval, separated by a hyphen (e.g., `YYYY-MM-DDTHH:MM - YYYY-MM-DDTHH:MM`). Date portions can be omitted if the interval date is today.

### Hints
Hints can be appended to the command to modify behavior:

- **:fill**:
  - For 'start' or 'end' subcommands: Fills the gap between the targeted interval and the next (for start) or previous (for end) interval.
  - For 'range' subcommand: Fills gaps on both sides of the modified interval.

- **:adjust**:
  - Forces the modification of the interval even if it overlaps with an existing interval, overwriting the existing one.

### Examples
*Modify the start date of an interval*
```bash
timew modify start @3 2020-12-28T17:00
```
This sets the start of interval '@3' to '17:00' on '2020-12-28'.

*Modify the end date of an interval (date omitted for today)*
```bash
timew modify end @3 18:00
```
This sets the end of interval '@3' to '18:00' today.

*Modify the range of an interval*
```bash
timew modify range @3 2020-12-28T17:00 - 2020-12-28T18:00
```
This sets the start and end of interval '@3' to the specified times on '2020-12-28'.

*Modify the range of an interval and fill gaps*
```bash
timew modify range @3 :fill
```
This modifies interval '@3' and fills any gaps between it and adjacent intervals.

*Modify an interval, adjusting for overlaps*
```bash
timew modify start @3 2020-12-28T17:00:adjust
```
This forces the start of interval '@3' to be '17:00' on '2020-12-28', overwriting any overlapping intervals.

### Error Handling
- If the resulting interval overlaps with an existing interval, an error is returned unless the ':adjust' hint is used.
- The new start or end datetime must be chronologically valid (e.g., end must be after start).

### See Also
- **timew-lengthen**(1)
- **timew-move**(1)
- **timew-resize**(1)
- **timew-shorten**(1)
- **timew-summary**(1)
```

--------------------------------

### Importing Other Rule Files

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/rules.txt

Use the 'import' keyword to include rules from other files. This allows for modular rule management.

```timewarrior-rules
import /path/to/other/rule/file
```

--------------------------------

### Continue tracking an interval via its ID

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-continue.1.adoc

To resume tracking of a specific interval, provide its ID (e.g., '@3') to the 'timew-continue' command. This creates a new open interval with the same tags as the specified interval, starting at the current time.

```bash
$ timew continue @3
```

--------------------------------

### Build Timewarrior with CMake

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/README.md

Build Timewarrior using CMake. Specify CMAKE_BUILD_TYPE for release builds. The build artifacts will be placed in the _build directory.

```bash
cmake -DCMAKE_BUILD_TYPE=release -S . -B _build
cmake --build _build -j
```

--------------------------------

### Display Day Chart with Interval IDs

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-chart.1.adoc

Use the 'day' command with interval IDs to filter the chart data. The '@' prefix indicates an ID.

```bash
$ timew day @3 @4
```

--------------------------------

### Run Timewarrior Tests

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/README.md

Optionally, run the Timewarrior test suite after building. This command requires CMake.

```bash
cmake --build _build --target timew_test
```

--------------------------------

### Test Source Files and Custom Target

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/test/CMakeLists.txt

Defines the source files for the test executable and creates a custom target to run the test suite. This facilitates automated testing.

```cmake
set (timew_test_SRCS AtomicFileTest data.t Datafile.t DatetimeParser.t exclusion.t helper.t interval.t range.t rules.t util.t TagInfoDatabase.t)

add_custom_target (timew_test ./run_all --verbose
                        DEPENDS ${timew_test_SRCS} timew_executable doc
                        WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/test
                        COMMENT "Running testsuite...")
```

--------------------------------

### Include and Link Directories

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/test/CMakeLists.txt

Specifies the directories for include files and libraries. This is essential for the compiler and linker to find project headers and dependencies.

```cmake
include_directories (${CMAKE_SOURCE_DIR}
                     ${CMAKE_SOURCE_DIR}/src
                     ${CMAKE_SOURCE_DIR}/src/libshared/src
                     ${CMAKE_SOURCE_DIR}/test)

include_directories (${CMAKE_INSTALL_PREFIX}/include)
link_directories(${CMAKE_INSTALL_PREFIX}/lib)
```

--------------------------------

### Include Subdirectories for Modules

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/CMakeLists.txt

Includes subdirectories for 'holidays' and 'themes' modules. These likely contain specific configurations or source files for those features.

```cmake
add_subdirectory (holidays)
add_subdirectory (themes)
```

--------------------------------

### Custom Target for Documentation Build

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/CMakeLists.txt

Defines a custom target 'doc' that depends on the 'man1' and 'man7' subdirectories. This allows building all documentation as a single target.

```cmake
add_custom_target (doc ALL DEPENDS man1 man7)
```

--------------------------------

### Display Month Chart with Date Range

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-chart.1.adoc

Use the 'month' command with a specific date range to view the chart. See timew-hints(7) for range options.

```bash
$ timew month 1st - today
```

--------------------------------

### Displaying Time Warrior Summary

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-fill.1.adoc

Shows the current time tracking summary before applying the fill command. This helps visualize the intervals.

```bash
$ timew summary

Wk  Date       Day ID Tags    Start      End    Time   Total
--- ---------- --- -- ---- -------- -------- ------- -------
W32 2025-08-10 Sun @3 FOO   8:00:00  9:00:00 1:00:00
                   @2 BAR  10:00:00 11:00:00 1:00:00
                   @1 BAZ  12:00:00 13:00:00 1:00:00 3:00:00
                                                     -------
                                                     3:00:00
```

--------------------------------

### timew continue

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/rfc_command_definition.md

The `continue` command restarts a previous time interval, optionally specifying which interval to continue.

```APIDOC
## timew continue [<id>]

### Description
Restarts a previous time interval. If no ID is provided, it defaults to the most recent interval (`@1`). This command is a shortcut for `timew start <tag-list-of-interval-with-given-id>`.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* `id` (string) - Optional - The ID of the interval to continue. Defaults to `@1` if not specified.

### Request Example
timew continue @2

### Response
#### Success Response (200)
No explicit output on success, operation is performed.

#### Response Example
(No output)
```

--------------------------------

### Tag Color Configuration

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-tags.1.adoc

Configuration for assigning specific foreground and background colors to tags.

```APIDOC
## Configuration: tags.<tag>.color

### Description
Assigns a specific foreground and background color to a tag. Examples of valid colors include 'white', 'gray8', 'black on yellow', and 'rgb345'.

### Method
CONFIGURATION

### Endpoint
N/A (Configuration setting)
```

--------------------------------

### Add multiple tags to multiple intervals

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-tag.1.adoc

Apply multiple tags to several intervals simultaneously by listing the interval IDs followed by the desired tags.

```bash
$ timew tag @2 @10 @23 'Tag One' tag2 tag3
```

--------------------------------

### TimeWarrior Duration Formats

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/rfc_command_definition.md

Shows different ways to specify durations in TimeWarrior.

```bash
one day
```

```bash
two weeks
```

```bash
today
```

```bash
yesterday
```

--------------------------------

### Override Confirmation for Timewarrior Configuration Changes

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-config.1.adoc

To bypass the interactive confirmation prompt when changing or clearing configuration values, append the ':yes' hint to the command.

```bash
$ timew config verbose "" :yes
```

--------------------------------

### Annotate multiple intervals

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/doc/man1/timew-annotate.1.adoc

This command allows you to apply the same annotation to multiple intervals simultaneously by listing their IDs. This is efficient for batch updates.

```bash
$ timew annotate @2 @10 @23 'Lorem ipsum'
Annotated @1 with "Lorem ipsum"
Annotated @10 with "Lorem ipsum"
Annotated @23 with "Lorem ipsum"
```

--------------------------------

### CMake Minimum Version and Policy Setting

Source: https://github.com/gothenburgbitfactory/timewarrior/blob/develop/test/CMakeLists.txt

Sets the minimum required CMake version and applies a policy workaround for older CMake versions. This ensures compatibility with specific CMake features.

```cmake
cmake_minimum_required (VERSION 3.10)

# This is a work-around for the following CMake issue:
# https://gitlab.kitware.com/cmake/cmake/issues/16062
# The issue has been fixed in CMake 3.11.0; the policy is set
# to OLD for compatibility with older versions of CMake only.
if (POLICY CMP0037 AND ${CMAKE_VERSION} VERSION_LESS "3.11.0")
  cmake_policy(SET CMP0037 OLD)
endif ()
```