habits.txt 1.0.1

No project description provided

habits.txt

habits.txt is a plain text habit tracker.

Features | Installation | Concepts | Format | Directives | Examples

Features

• Track habits in a plain text file
• Track boolean (done/not done) habits or measurable habits/metrics (e.g. weight)
• Custom and complex frequencies for habits (daily, on Monday and Friday, on the 1st every month, etc...)
• Get stats about your habits with the CLI or with charts opening in your browser

Installation

pip install habits.txt

You can then use the CLI with:

hbtxt --help

Alternatively, you can use the executable provided by the latest release.

Concepts

Time-bound

A habit is time-bound. It has a start date, and eventually an end date. It means with habits.txt, you can track habits for a specific period of time. When you want to stop tracking a habit, you can just stop tracking it.

Frequency

A habit is defined by a frequency, else it's called a task. The minimum frequency supported by habits.txt is daily (it doesn't support intra-day habits).

Boolean or Measurable

A habit can be boolean or measurable. A boolean habit is either done or not done. A measurable habit has a value.

Format

Habits are tracked in what I call a "journal" which is just a plain text file. A journal contains "directives".

A directive is composed of a date, a directive type, a habit name, and other metadata specific to the directive type. For example, here is a sample directive:

2024-01-01 track "Read 5 pages a day" (* * *)

You can comment lines in your journal by starting them with a # character. You can't add comments at the end of a line.

# Start tracking a habit
2024-01-01 track "Read 5 pages a day" (* * *)

Directives

track

To start tracking a habit, you use the track directive and specify the frequency of the habit enclosed in parentheses. Optionally, you can make the habit measurable by specifying the "measurable" keyword.

The frequency follows a simplified cron syntax, omitting the minute and the hour.

Example:

2024-01-01 track "Read 5 pages a day" (* * *)
2024-01-01 track "Exercise" (* * 1,3,5) measurable

untrack

To stop tracking a habit, you use the untrack directive.

Example:

2024-02-01 untrack "Read 5 pages a day"

record

To record a habit, you use the record directive and specify a value.

The allowed values are yes, no, or a number. You should not mix boolean and numeric values for the same habit.

You can write directives but omit the directive type, it will default to record (as it is supposed to be the most common directive).

Example:

2024-01-01 record "Read 5 pages a day" 5
2024-01-01 record "Workout" yes
2024-01-01 "Weight" 70.5

Examples

habits.journal:

2024-01-01 track "Reading" (* * *)
2024-01-01 track "Exercise" (* * 1,3,5)
2024-01-01 track "Weight" (* * 1) measurable

# Record habits
2024-01-01 record "Reading" yes
2024-01-01 record "Exercise" no
2024-01-01 record "Weight" 70.5

Once your journal is ready, you can use the CLI to interact with it.

# Set the journal file as default journal
hbtxt config set journal /path/to/habits.journal

# Fill the habits for today interactively
hbtxt fill -i
Exercise (2024-01-01): yes

# Filter habit records
hbtxt filter -n "Exercise"
2024-01-01 Exercise yes

# Get information about the other available commands
hbtxt --help

# Get information about a given command
hbtxt chart --help

# Get information about the available config options
hbtxt config set --help