Skip to content
benburkPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

33 Commits

Folders and files

Repository files navigation

tk

A lightweight, git-backed ticket tracker that stores tickets as Markdown files in your repository. No external services, no databases—just files that version with your code.

Install

# Cargo
cargo install --path .

# Nix
nix profile install github:benburk/ticket#tk

Quick Start

Demo

tk init                              # Create .tickets/ directory
echo "# Fix login bug" | tk create   # Create a ticket from stdin
tk list                              # See all tickets
tk -C ../another-repo ready          # Read another repo without cd
tk ready                             # See what's ready to work on
tk close tk-a1b2                     # Close a ticket

Key Features

  • Git-native storage — Each ticket is a Markdown file in .tickets/, making diffs readable and merges easy
  • Dependency tracking — Model blocking relationships with tk dep and see what's actionable with tk ready
  • Tags — Organize tickets with --tags backend,urgent and filter with --tag backend
  • Unix-friendly — Ticket-returning commands support --json for piping to jq and other tools
  • Offline-first — No server, no sync, no account; tickets live in your repo
  • Prefix matching — Reference tk-a1b2c3d4 as just tk-a1 when unambiguous

Usage

tk [OPTIONS] <COMMAND>

Commands:
  init       Initialize ticket tracking in current directory
  create     Create a new ticket from stdin (expects "# Title" on first line)
  list       List tickets
  show       Show a ticket
  edit       Replace ticket title + body from stdin (expects "# Title" on first line)
  status     Change ticket status
  close      Close a ticket
  reopen     Reopen a ticket
  dep        Add a blocking dependency
  undep      Remove a blocking dependency
  ready      List tickets ready to work on (open, no unresolved deps)
  blocked    List blocked tickets (open, has unresolved deps)
  dep-cycle  Detect dependency cycles
  tree       Show dependency tree (all tickets if no ID given)
  note       Add a timestamped note to a ticket
  query      Query tickets as JSON (pipe to jq)
  help       Print this message or the help of the given subcommand(s)

Options:
  -C, --directory <PATH>  Run as if started in this directory
      --json              Output in JSON format
  -h, --help              Print help
  -V, --version           Print version

Run tk <command> --help for command-specific options. Read commands fail when .tickets/ is absent; only tk init creates it. tk --json show <id> includes the Markdown body and every timestamp.

Ticket Format

---
id: tk-a1b2
status: open
created: 2024-01-15T10:30:00Z
deps:
  - tk-c3d4
tags:
  - backend
---

# Implement user authentication

Add JWT-based auth with refresh tokens.

[2024-01-15 10:45 alice] Started research on JWT libraries
[2024-01-15 14:30 alice] Going with jsonwebtoken crate

Rust API

The package exports the same parser and store used by tk:

use ticket::Store;

let store = Store::open("/path/to/repo");
let tickets = store.load_all()?;
let ticket = store.create("Fix login".into(), String::new(), vec!["auth".into()])?;
store.close(ticket.id())?;

The library owns ticket files and dependency rules. It does not run Git or manage branches, worktrees, agents, or CI.

Philosophy

See PHILOSOPHY.md for the design rationale and recommended git workflow.

Inspiration

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages