simple-project-tracker

A simple, but very customizable tracker to keep track of your projects, their states and your notes on them.

TID | ID | NAME                          | STATUS  | LAST TOUCHED | NOTE
--- | -- | ----------------------------- | ------- | ------------ | ---------------------
1   | 8  | tracker                       | dev     | 1m ago       | release 1.0.0 today
2   | 3  | von-neumann-machine-simulator | dev     | 23m ago      | review saturday
3   | 26 | discord-profile-studio        | stable  | 1h ago

Contents

• Install
• Commands
• Todos
• Selecting projects
• Several machines
• Configuration
• Development
• License

Install

./install.sh             # ~/.local
sudo ./install.sh        # /usr/local
./install.sh --daemon    # also install the daemon autostart entry
./install.sh --uninstall

Python 3.11+. Then t init ~/(your project directory) to fill the database.

Commands

t on its own lists your projects. With output.browser on it opens a browser instead: your monitored folders as a tree, each project's status and last change, and the check view of the selected one beside it. Arrows move and fold, enter opens the details, ? lists every key: search, every project instead of the filtered ones, a flat list, the full tree, sorting, one status at a time. Tab switches to your todos and the projects each one is about. q quits. Piped, or with t list, it prints the table instead.

The project goes before or after the command, whichever reads better, and a command fuses with its own action:

t 12 es blocked        # edit status  also: t edit 12 status blocked
t 12 sn review sunday  # set note     also: t note 12 review sunday
t dst                  # daemon status
t sset ll 30           # settings set display.list_limit 30

A bare word defaults to a project lookup.

t tra          # the check view for tracker
t stable       # nothing is called that, so every stable project
t all          # everything with no limit and no filter

For more information do: t help, t help <command> or t help <topic>. The full guide is within man tracker.

Todos

List of notes that's separate from the main project database.

t td                          # the whole list
t td add write the changelog  # the rest of the line is the name
t td add milk s shop n oat    # with a status and a note up front
t td 3 done                   # also: t td done 3
t td 3 st blocked             # any status you like
t td 3 n waiting on review    # and a note under it
t td write the docs n today   # by name; offers to add one that is not there
t td list s:todo              # only what is still open
t td clear                    # drop every finished one
t td undo                     # take the last change back

TID | ID | NAME                  | STATUS  | CREATED    | NOTE
--- | -- | --------------------- | ------- | ---------- | ----------------------
1   | 1  | write the changelog   | todo    | 2m ago     | blocked on the release
2   | 2  | fix the daemon logs   | done    | 1h ago
3   | 3  | ship the todo feature | review  | 1h ago     | shipped on a sunday
3 todos, 2 left  (2 todo, 1 done)

A todo is selected exactly the same way a project is, and the same short forms apply.

A note may point at a project with @name, printed as name#id:tid in that project's status colour. t check <project> then lists the todos about it, and t td check <todo> the projects it names.

Selecting projects

A temporary ID is the index of the latest output.

When a partial name matches several projects, it's settled by projects.conflict_resolution_preference.

Several machines

The database can live in a Syncthing, Dropbox or git folder.

t mv db ~/sync-folder/data.pkl   # put the database where it syncs
t doctor                         # what is wrong with it
t fix                            # put that right, undoable

[sync.roots]
media = "/archives/media"        # stored as @media/photos, wherever media points

Roots belonging to one machine alone go in ~/.config/tracker/roots.toml, which holds the same table and stays out of whatever syncs the settings.

$ t doctor

Tracked twice (2)
  one project under two entries, the older one pointing at a path that is gone

  von-neumann-machine-simulator #3 -> #61, by fingerprint
      gone  ~/Programming/Development/Rust/von-neumann-machine-simulator
      here  ~/programming/development/rust/von-neumann-machine-simulator

fix keeps the older entry's ID, status and note and the living entry's path and timestamp. Two different notes are joined rather than one being dropped, and t undo takes the whole repair back.

Configuration

t settings                    # everything (default deviations marked)
t settings edit               # open in $EDITOR
t sset list_limit 30          # rewrites that one line
t list ll=5 rt=true           # override for one command only

A setting can be named in full, by its bare name, by a prefix, by the start of every word or by its initials, with the section shortening the same way: display.list_limit, list_limit, list_lim, l_l, ll, d.ll. Ambiguities are reported.

Notes can colour themselves: t note 12 {red}broken{/} since friday.

Development

make dev      # editable install plus ruff, basedpyright, pytest
make check    # format, lint, types and tests (what CI runs)

Disclosure

LLMs were used to:

• write tests
• write the man page
• write the help section
• check for critical issues and annotation errors

HOWEVER, the output was then manually reviewed and issues were fixed by a human.
I wanted to get this project out asap as I really needed it :P

License

MIT LICENSE. By MattFor.