pal

Your Personal Activity Log

Your activity log is a lightweight record of the low level tasks that you have performed over time.

Stop fishing your git log and Slack messages to remember past activities.

Quick Start

Run the pal executable to log the latest activities

$ pal

Run comes with a set of commands to manage your activities:

$ pal commit "Hey, This is a new activity"

And then you can see it with

$ pal log

Once you have already reported your current activity, you can mark them and they will not appear in later logs.

$ pal report

$ pal log

(You can always show them again with the -r/--include-reported flag)

Once you finished with a project, you can cleanup the old entries:

$ pal clean

See the Usage Guide for more information and advanced usage.

Installation

pal is distributed as a Python package. You can install it using pip at pal-log:

$ pip install pal-log

At this point you can start using pal normally.

$ pal

An alternative way is to use the github repo directly. For that, clone this repo and run:

$ pip install .

And the pal executable should be ready for use.

Development

For development you can use the dev extra, like so:

$ pip install -e '.[dev]'

Which will install pal with all the development dependencies. This project has pre-commit for automated linting / formatting.

We recommed you install it and setup in this repo. For that, follow the installation instructions, and then run the following command at the root of the repo:

$ pre-commit install

At this point, a set of automated checks will run before you can git commit your changes.

You can manually run the checks as well with:

$ pre-commit run [--all-files]

Usage Guide

Apart from the basic usage, PAL also contains other concepts that make it more useful for more complex scenarios:

• It contains the notion of author: every entry is associated to an author. You can use -a/--author or the PAL_AUTHOR environment variable to change the author when commiting or displaying the entries.
• It contains the notion of project: every entry is associated to an project. You can use -p/--project or the PAL_PROJECT environment variable to change the project when commiting or displaying the entries.

These two act as namespaces that make it easy to use pal when working on multiple projects. However, pal provides default values for those so that is easier to get started.

• author: the default author is the OS username ($USER env variable). This is the one that you will be using most often. You can change it for instance to keep work and personal projects.
• project: the default project is default. You are encouraged to use as many as you like.

If you specify both an env variable and a CLI argument, the CLI argument will have priority.

The fact that these are controlled with environment variables make this specially interesting when combined with tools like direnv or other tools that automatically change environments based on directory specific configurations.

You can have an entry so that your PAL_PROJECT is set to a given project and you can quickly log the activities for this particular project / repo. When you are ready for reporting your advances, you can just call:

$ pal

And the most recent (unreported) tasks will show up. Once you are done with them, mark them as reported:

$ pal report

And continue working.

Integrations

PAL is mainly intended as the final consumer of the information. However, you can request the log output as --json, which you can then feed to jq or other tools to build a pipeline.

$ pal log --json | jq .
[
  {
    "text": "Added new documentation",
    "author": "alvaro",
    "project": "default",
    "timestamp": "2023-10-20T23:23:58.985532",
    "reported": false,
    "created_at": "2023-10-20T23:23:58.985609+02:00",
    "updated_at": "2023-10-20T23:23:58.985609+02:00"
  },
  {
    "text": "Created a new feature",
    "author": "alvaro",
    "project": "default",
    "timestamp": "2023-10-20T23:23:42.937248",
    "reported": false,
    "created_at": "2023-10-20T23:23:42.937330+02:00",
    "updated_at": "2023-10-20T23:23:42.937330+02:00"
  },
  {
    "text": "Fixed a bug in the CLI",
    "author": "alvaro",
    "project": "default",
    "timestamp": "2023-10-20T23:23:32.699920",
    "reported": false,
    "created_at": "2023-10-20T23:23:32.700029+02:00",
    "updated_at": "2023-10-20T23:23:32.700029+02:00"
  },
  {
    "text": "Welcome to PAL",
    "author": "alvaro",
    "project": "default",
    "timestamp": "2023-10-20T23:23:07.721046",
    "reported": false,
    "created_at": "2023-10-20T23:23:07.721125+02:00",
    "updated_at": "2023-10-20T23:23:07.721125+02:00"
  }
]

How it works

PAL is just a CLI to record timestamped entries on a log.

Currently, the log is a simple SQLite database stored in your user files. You can inspect it with any SQLite compatible tool:

$ sqlite3 $(pal --show-db) 

And start querying your database.

Each entry contains a timestamp and a reported boolean flag that control how and if they are displayed with pal log.