Plain Text Exercise Notation

I've been recording my exercise/workout routines for 15 years now, and having a historical record of what I did and when has proven quite useful over the years for a few reasons:

  1. Knowing whether or not I'm progressing.
  2. Getting program inspiration from what I've done in the past.
  3. Seeing what's worked and in what context.

On a few occasions, I've started using various apps to log my exercise. Without fail, I always stop using that app and revert back to just plain ol' text files, and I tend to forget to export my logs from the now abandoned app. This begs the question of why I ever use an app if I like text based logging so damned much? Well, an app provides me with a way of analysing my workouts over time, total sets per week, total sets per body part, average rest etc...

So, how do I get that functionality without leaving my beloved text files? Some sort of parse-able format! I already log in a relatively structured way, but if I take the time to formalise it, and then stick to it, then I can write scripts to parse over my files (or even files within a directory) and run analysis on them!


A formal specification for exercise logging notation MUST be able to do the following:

  1. Show the order in which exercises were performed.
  2. Show the sets, reps, and weights/resistance/difficulty used.
  3. Show the tempo (often abbreviated to 30X0 or something of that kind - meaning 3 seconds eccentric, 0 second pause at bottom, explosive concentric, 0 second pause at the top).
  4. Show set style (rest-pause, extended sets, cluster sets etc...).
  5. Group exercises into circuits.
  6. Name sections of workouts.
  7. Handle non rep/sets/weights based exercises (e.g duration, distance, speed as variables).
  8. Show the duration of exercises or segments of exercises.
  9. Be easy to read.
  10. Be readable by a script.

(10 requirements... that was lucky).


Structure and Metadata

With regards to structuring workouts in text, we need some of the following traits:

  1. Program name
  2. Program metadata
  3. Workout name
  4. Workout metadata

we can declare a program by using a markdown header symbol, and mark any metadata for the program directly below it by wrapping it in --- three dashes:

# My great new program
date: 04/04/2024
notes: some notes about why I'm choosing to do this program

we can declare a workout by using the double hash symbol (level 2 header in markdown) and then the date on which the workout was performed.

## 13/05/2024
name: A big workout
notes: some interesting notes about the workout...

Every program must get it's own text file, with the program name and metadata at the top. However, there are periods of time where no program is being followed, and for those a text file might simply be a long append-only style log of workouts.

Exercise Declaration

An exercise is declared by giving it an order in the workout, naming it, and then detailing it.

A. Bench Press [20X0]: 3x10@100kg (60s)
B. Pull ups: 3x10@bw (45s)
C. Curls [Rest-pause]: 8+5+2@20kg

With regards to the syntax and meaning of the exercise declaration:

  1. the A. denotes the order in the workout the exercise is performed
  2. The name of the exercise
  3. the rep style declared in square brackets - this is a loose descriptor, so it can be a tempo (as in [20X0]) or a rep style (as in [Rest-pause] or [extended-set])
  4. the sets and reps and weights: 2x10@10kg denoting: 2 sets of 10 reps at 10 kilograms. If only one set is being completed, then the set declaration can be omitted (e.g: 10@10kg meaning 1 set of 10 reps at 10 kilograms)
  5. the rest time between sets, declared in regular brackets.

Here are some valid examples of how to declare exercises, reps, sets, effort etc..

A. Bench Press: 3x10@100kg, 12@90kg, 15@80kg (60s)

or the same can be written as :

A. Bench Press:
    3x10@100kg (60s)
    12@90kg (60s)
    15@80kg (60s)

notice that on the one line declaration, the rest time is only declared at the end - making implicit that the same rest is being used between all sets, whereas on the multI line declaration, the rest time is declared after each line. Both approaches work, and the single rest time declaration can be used on the multiline rep declaration as well.

A grouping of exercises (usually denoting a super-set, or a circuit) can be declared as:

A. Bench Press: 3x10@100kg (60s)
B1. Curl: 10@20kg
B2. Extension: 20@20kg
B3. Sit-ups: 20
x2 (60s)

Here we use the letter B to denote that it comes after exercise A, and then enumerate 1 through 3 for the sub order of the exercises. The sets of the tri-set or circuit are presented at the bottom x2 with the rest between circuits as (60s). Note that it is also possible to declare rest time between elements within a circuits, eg: B2. Extension: 20@20kg (30s).

It is sometimes useful to refer to a circuit by name (for example, certain 'Crossfit girls' workouts). The - at the start and end of the circuit segment allow us to encapsulate additional data.

name: Mary
result: 15 + 7

C1. Handstand push-ups: 15x5, 1x7
C2. 1-legged squats, alternating legs: 15x10
C3. Pull ups: 15x15

This syntax highlights some interesting facts about the way groupings are interpreted. It is implicit in a grouping, that a set of an exercise is only repeated once all the other exercises in the grouping have been performed. For example, in the above grouping 15x5 does not imply that 15 sets of 5 reps of exercise C1 were performed before moving on to C2, but rather that 15 sets were performed over all, in the prescribed order C1 -> C2 -> C3. The 1x7 on C1 means that an additional set of 7 reps was performed for this one exercise. This further implies that it is not possible to log more sets for C2 than for C1, nor is it possible to perform more than 1 extra set for C1 than the other exercises in the grouping.

Rest between sets versus rest after sets

The notation A. Bench press: 3x10@100kg (60s) states that 60s of rest was taken between each set of bench press. In the case that we wish to state that additional rest was taken between bench pressing and the subsequent exercise, especially where that rest is a feature of the workout, then ascribe it it's own letter, eg:

A. Bench press: 3x10@100kg (60s)
B. (120s)
C. Pull ups: 3x10@bw (60s)

Exercise duration

The duration of an exercise, should we wish to track it, can be noted down inline and after the exercise, e.g:

A. Bench press: 3x10@100kg (60s) 4mins 27s

We've already seen this form of notation in the exercise grouping section, where the grouping titled mary was set to 20mins


I need to work on a better name than Plain Text Exercise Notation...