tally

tally is a lightweight, Git-friendly task manager for projects that live in a TODO.md file.

It lets you track tasks, mark them complete, associate them with git commits or releases, and automatically generate changelogs — all from the command line, without a database or daemon.

Table of Contents

1. Features
2. Installation
   • Install via Cargo
   • Build from Source
3. Getting Started
4. Usage
   • Initialize
   • Add Tasks
   • List Tasks
   • Complete Tasks
   • Release Management
   • Changelog Generation
   • Task Cleanup
   • Git Integration
   • Editing Tasks
   • Cross-Project Commands
5. Configuration
6. Storage Format

Features

• Uses a plain TODO.md file as storage
• Fuzzy-matching to find tasks by description
• Tags and priorities for better organization
• Automatic changelog generation from completed tasks
• Associate tasks with git commits or release versions
• Prune or archive old completed tasks
• Scan git history to detect completed tasks
• Global project registry with cross-project status

Installation

Install via Cargo

tally is written in Rust and can be installed with Cargo:

cargo install tally-todo

To update:

cargo install --force tally

Build from Source

git clone https://github.com/what386/tally.git
cd tally
cargo build --release

Binary location:

target/release/tally

Getting Started

Initialize tally in your project directory:

tally init

This creates:

• TODO.md — your task list
• .tally/ — configuration and history files

It also registers the project in ~/.config/tally/projects.json. Running tally init again is safe and will re-register existing projects.

Usage

Git Commit Integration

tally can automatically detect completed tasks by scanning git commit messages.

This works by looking for a special done: section in commit messages and fuzzy-matching the listed items against tasks in TODO.md.

Commit Message Format

Add a done: section anywhere in your commit message:

do thing

done:
fix parsing issue

Each line under done: is treated as a potential completed task.

Lists Are Supported

You can use plain lines, dash lists, or bullet lists:

refactor parser

done:
- fix parsing issue
- handle edge cases

cleanup

done:
* update docs
* remove unused code

tally strips common list markers (-, *) before matching.

Fuzzy Matching

Task names do not need to match exactly.

For example, this task in TODO.md:

- Fix parsing error in format.rs

Will match any of the following commit entries:

fix parsing issue
parsing error
fix parser

Scanning Commits

To scan git history for completed tasks:

tally scan

Preview matches without making changes:

tally scan --dry-run

Automatically mark all detected matches as done:

tally scan --auto

When a task is marked complete via a commit scan, the commit hash is automatically associated with the task.

Initialize

tally init

Initializes tally in the current directory.

Add Tasks

tally add "Fix parsing error"

With priority and tags:

tally add "Implement feature" --priority high --tags feature,backend

Preview without writing:

tally add "Update docs" --dry-run

List Tasks

tally list

Filter by tags and priority:

tally list --tags bug,parser --priority high

Output as JSON:

tally list --json

Complete Tasks

Mark a task as completed using fuzzy matching:

tally done "Fix parsing error"

Associate a git commit:

tally done "Fix parsing error" --commit abc123f

Associate a release version:

tally done "Fix parsing error" --version v0.2.3

Preview changes:

tally done "Fix parsing error" --dry-run

Version Management

Assign a version to all completed, unversioned tasks:

tally semver v0.2.3

Show a summary:

tally semver v1.0.0 --summary

Automatically make a git tag, too:

tally tag v0.2.4

Changelog Generation

Generate a changelog from completed tasks:

tally changelog

From a specific version:

tally changelog --from v0.2.2

Between versions:

tally changelog --from v0.2.2 --to v0.2.3

Task Cleanup

Remove a task entirely:

tally remove "Old task"

Completed tasks are archived to history.json before removal.

Prune completed tasks older than a threshold:

tally prune            # default: 30 days
tally prune --days 7
tally prune --days 1 --hours 12
tally prune --dry-run

Git Integration

Scan git commit messages for completed tasks:

tally scan

Automatically mark matches as done:

tally scan --auto

Preview matches:

tally scan --dry-run

Editing Tasks

Open TODO.md in your editor:

tally edit

Uses:

1. preferences.editor from tally config
2. $EDITOR
3. Common fallbacks (vim, nano, etc.)

Cross-Project Commands

List registered projects:

tally projects list

Show an aggregated status across all registered projects:

tally projects status

Remove missing entries from the global registry:

tally projects prune

Configuration

Configuration is stored in:

./.tally/config.toml (optional, per-project)
~/.config/tally/config.toml (fallback)

Manage configuration via:

tally config <action>

Available actions:

Examples:

tally config set preferences.editor vim
tally config get preferences.editor
tally config list

Storage Format

• TODO.md — active tasks
• .tally/history.json — archived completed tasks
• .tally/config.toml or ~/.config/tally/config.toml — user preferences
• ~/.config/tally/projects.json — registry of initialized projects

All data is human-readable and git-friendly.

Philosophy

tally is designed to:

• Stay out of your way
• Work naturally with git
• Avoid lock-in and opaque formats
• Make changelogs easy