Skip to content
Manage your repository's TODOs, tickets and checklists as config in your codebase.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows run the test workflow on PRs Dec 29, 2019
cmd minor change to language, some spacing Dec 14, 2019
docs some rewording Nov 1, 2019
pkg preview file content when identifying language Jan 18, 2020
testdata/repos/repo-001/commit-001 initial commit, very basic implementation Oct 12, 2019
.goreleaser.yml github token for homebrew Oct 20, 2019
LICENSE add an MIT License Oct 25, 2019 Update TODOs badge in README Jan 25, 2020
go.mod upgrade deps Dec 29, 2019
reports.go remove a dangling colon Oct 12, 2019
tickgit.go some minor fixes from linter Oct 14, 2019
todo.tickgit tweak readme, complete a todo (#5) Oct 20, 2019

GoDoc BuildStatus Go Report Card GitHub release (latest SemVer) Coverage TODOs

tickgit 🎟️

tickgit is a tool to help you manage tickets, todo items, and checklists within a codebase. Use the tickgit command to view pending tasks, progress reports, completion summaries and historical data (using git history).

It's not meant to replace full-fledged project management tools such as JIRA or Trello. It will, hopefully, be a useful way to augment those tools with project management patterns that coexist with your code. As such, it's primary audience is software engineers.


tickgit todos will scan a codebase and identify any TODO items in the comments. It will output a report like so:

# tickgit todos ~/Desktop/facebook/react
  => packages/scheduler/src/__tests__/SchedulerBrowser-test.js:85:9
  => added 1 month ago by Andrew Clark <> in a2e05b6c148b25590884e8911d4d4acfcb76a487

TODO: Scheduler no longer requires these methods to be polyfilled. But
  => packages/scheduler/src/__tests__/SchedulerBrowser-test.js:77:7
  => added 1 month ago by Andrew Clark <> in a2e05b6c148b25590884e8911d4d4acfcb76a487

TODO: Scheduler no longer requires these methods to be polyfilled. But
  => packages/scheduler/src/forks/SchedulerHostConfig.default.js:77:7
  => added 1 month ago by Andrew Clark <> in a2e05b6c148b25590884e8911d4d4acfcb76a487

TODO: useTransition hook instead.
  => fixtures/concurrent/time-slicing/src/index.js:110:11
  => added 3 weeks ago by Sebastian Markbåge <> in 3ad076472ce9108b9b8a6a6fe039244b74a34392

128 TODOs Found 📝

Check out an example of the TODOs tickgit will surface for the Kubernetes codebase.

Coming Soon

  • History - get a better sense of how old TODOs are, when they were introduced and by whom
  • Context - more visibility into the lines of code around a TODO for greater context


Tickets are a way of defining more complex tasks in your codebase as config files. Currently, tickets are HCL files that look like the following:

# rocketship.tickgit

goal "Build the Rocketship 🚀" {
    description = "Finalize the construction of the Moonblaster 2000"

    task "Construct the engines" {
        status = "done"

    task "Attach the engines" {
        status = "pending"

    task "Thoroughly test the engines" {
        status = "pending"
$ tickgit status
=== Build the Rocketship 🚀 ⏳
  --- 1/3 tasks completed (2 remaining)
  --- 33% completed

  ✅ Construct the engines
  ⏳ Attach the engines
  ⏳ Thoroughly test the engines

Coming Soon

  • Simpler ticket definitions - in YAML and/or other (less verbose) config languages
  • More complex tickets - more states, dependencies on other tickets, etc


Coming soon. Checklists will be a way of parsing Markdown checklists in your codebase (either in .md files, or within your comments).

Why is this useful?

This project is a proof-of-concept. Keeping tickets next to the code they're meant to describe could have the following benefits:

  • Tickets live with the code, no need for a 3rd party tool or system (anyone with git access to the repository has access to contributing to the tickets)
  • Updating a ticket's status and merging/committing code are the same action, no need to synchronize across multiple tools
  • Source of truth for a project's ticket history is now the git history, which can be queried and analyzed
  • Current status of a goal can be reported by simply parsing the repository's head
  • Less context switching between the codebase itself and the system describing "what needs to be done"

Generally speaking, this is an experiment in ways to do project management, within the codebase of a project. With a git history and some clever parsing, quite a bit of metadata about a project can be gleaned from its codebase. Let's see how useful we can make that information.



brew tap augmentable-dev/tickgit
brew install tickgit


The most up to date usage will be the output of tickgit --help. The most common usage, however, is tickgit status which will print a status report of tickets for a given git repository. By default, it uses the current working directory.


To find information about using the tickgit API, see this file.

You can’t perform that action at this time.