Bartib File Format

Bartib stores all activities in a plain text file, one activity per line. The file is human-readable and can be edited manually in any text editor.

Line Structure

Each line represents one activity and follows this structure:

START_TIME | PROJECT | DESCRIPTION

For a stopped (completed) activity with an end time:

START_TIME - END_TIME | PROJECT | DESCRIPTION

Fields are separated by | (space, pipe, space). The description field is optional — a line with only start time and project is valid.

Timestamp Format

Timestamps use ISO 8601 local time, without timezone information.

Default (minute precision):

YYYY-MM-DD HH:MM

With second-precision compile feature:

YYYY-MM-DD HH:MM:SS

Examples

A currently running activity (no end time):

2021-02-16 16:14 | my project | writing documentation

A stopped activity:

2021-02-16 16:14 - 2021-02-16 18:23 | my project | writing documentation

An activity without a description:

2021-02-16 16:14 | my project

Special Character Escaping

The pipe character | is used as a field delimiter, so it must be escaped inside project names and descriptions. The backslash \ is the escape character.

Character	Escaped form
|	literal pipe `
\\	literal backslash \ in a field value

Example — a project named client|work and a description containing a backslash:

2021-02-16 16:14 - 2021-02-16 18:23 | client\|work | path: C:\\Users\\alice

This parses to:

• project: client|work
• description: path: C:\Users\alice

Handling Precision Mismatches

When the compiled precision of a bartib binary differs from the precision used in the file, bartib handles it gracefully:

• Minute-precision binary reads second-precision timestamps: rounds to the nearest minute, prints a warning.
• Second-precision binary reads minute-precision timestamps: sets seconds to zero, prints a warning.

This means files can be shared across builds of different precision without data loss.

Sanity Checks

The bartib sanity subcommand checks a file for logical errors and prints a warning for each one found. If no problems are detected it prints No unusual activities.

Before checking, all successfully parsed activities are sorted by start time. Lines that cannot be parsed are silently ignored.

Two conditions are flagged:

Negative duration

An activity whose end time is earlier than its start time. This can happen if a line is edited manually and the timestamps are accidentally swapped or mistyped.

2021-02-16 18:23 - 2021-02-16 16:14 | my project | oops, end before start

Overlapping activities

An activity that starts before a previous activity has ended. The check tracks the latest end time seen so far (across all prior activities sorted by start); if the current activity's start is earlier than that, it is reported as an overlap.

2021-02-16 09:00 - 2021-02-16 11:00 | project a | first task
2021-02-16 10:30 - 2021-02-16 12:00 | project b | overlaps with first task

For each flagged activity, the subcommand prints the description, start time, end time, and line number to help locate and fix the problem.

Multiple Simultaneously Running Activities

The file format places no restriction on how many activities may be running at the same time — any number of lines without an end time is valid. This situation can arise when the file is edited manually.

Bartib's own commands always prevent accidental accumulation of running activities: bartib start and bartib continue stop all currently running activities before recording a new one. Likewise, bartib stop and bartib cancel act on all running activities at once, as does bartib change.

bartib current lists all running activities, so multiple entries will all be shown.

The bartib sanity subcommand does not flag multiple simultaneous running activities as an error. If that situation is unintentional it can be corrected by manually adding end times to the unwanted entries, or by running bartib stop to close all of them at once.

File Behaviour

• Lines that cannot be parsed are silently skipped when reading activities, but are preserved as-is when the file is written back. This means comments or malformed lines are not lost.
• The file is not sorted; activities appear in the order they were recorded.
• The file path is configured via the --file / -f command-line flag or the BARTIB_FILE environment variable. The file is created automatically if it does not exist.