Timewarrior Command-Line Time Tracking for Linux

Timewarrior is an open-source command-line time-tracking utility designed to help users record work sessions, manage activities, and generate detailed time reports. It combines simple stopwatch functionality with calendar-based time entry, allowing users to track both ongoing tasks and activities recorded after they have finished.

Developed as a portable and actively maintained project, Timewarrior provides flexible reporting features without requiring a graphical interface. Its command-line workflow makes it suitable for developers, system administrators, freelancers, and anyone who wants to understand how their time is distributed across projects and daily activities.

Key Features of Timewarrior

• Command-line time tracking: Start and stop timers directly from the terminal.
• Calendar-based backfill: Record activities that happened earlier instead of tracking only live sessions.
• Flexible reporting: Generate reports to review time spent on different tasks and date ranges.
• Portable design: Run the utility on supported operating systems without relying on a web-based tracking service.
• Open-source development: Inspect the source code, contribute improvements, and customize the software.
• Task and tag organization: Associate tracked intervals with tags to make reporting and activity analysis easier.

Installing Timewarrior

Timewarrior can be installed through available distribution packages or compiled from its source code. Package installation is generally the simplest option, while building from source provides more control over the version and installation location.

Install From a Distribution Package

Community-maintained binary packages are available for several Linux distributions. Check the official installation documentation for supported package sources and platform-specific instructions.

View Timewarrior distribution installation options.

Build Timewarrior From Source

Building Timewarrior requires a C++ development environment and a few supporting tools. Install the following dependencies before starting:

• Git: Retrieves the project source code.
• CMake: Configures the build system.
• Make: Executes the compilation process.
• C++ compiler: GCC or Clang with the required C++11 support.
• Python 3: Runs the project’s test suite.

The exact compiler and dependency versions may vary between releases. Check the repository’s build instructions if you encounter compatibility issues.

1. Retrieve the Source Code

Clone the GitHub repository and include its submodules:

git clone --recurse-submodules https://github.com/GothenburgBitFactory/timewarrior.git
cd timewarrior

Alternatively, download a release archive. The following example uses version 1.4.2 from the original installation instructions:

curl -LO https://github.com/GothenburgBitFactory/timewarrior/releases/download/v1.4.2/timew-1.4.2.tar.gz

tar xzf timew-1.4.2.tar.gz
cd timew-1.4.2

For new installations, check the official GitHub releases page and select a version appropriate for your environment rather than assuming the older example is the latest release.

2. Configure and Compile

Run CMake to configure the project with release build settings:

cmake -DCMAKE_BUILD_TYPE=release .

Compile the source code:

make

3. Run the Test Suite

Running the tests is optional, but it can help identify build or compatibility problems before installation. If you cloned the repository with its required submodules and test resources, run:

make test

Note that the release tarball mentioned in the original instructions does not include the test suite, so this step may not be available when building from that archive.

4. Install Timewarrior

Install the compiled application and its associated documentation:

sudo make install

By default, CMake installs files under /usr/local. The command may not require administrator privileges if the selected installation directory is writable by your user account.

To choose a different installation directory, configure CMake with -DCMAKE_INSTALL_PREFIX:

cmake -DCMAKE_BUILD_TYPE=release \
  -DCMAKE_INSTALL_PREFIX=/path/to/your/install/location .

Then compile and install using the same build steps.

Documentation and Project Resources

Timewarrior includes extensive documentation covering installation, time tracking, configuration, tags, and reporting. The official documentation is the best place to learn the available commands and understand how to organize tracked activities.

• Official documentation: Timewarrior documentation
• Installation guide: Installation instructions
• GitHub repository: Timewarrior source code
• Downloads: Available releases

For developers who regularly work from the terminal, combining time tracking with efficient command-line workflows can make daily activity management easier. Explore our guide to Linux shell commands and workflows for more terminal-based tools and techniques.