Most of this section is an edited part of the README file from the original Ditz.

About PyDitz

  • PyDitz is a simple, light-weight distributed issue tracker designed to work with distributed version control systems like git, darcs, Mercurial, and Bazaar. It can also be used with centralized systems like SVN.
  • PyDitz maintains an issue database directory on disk, with files written in a line-based and human-editable format. This directory can be kept under version control, alongside project code.
  • PyDitz provides a simple, console-based interface for creating and updating the issue database files, and some basic static HTML generation capabilities for producing world-readable status pages.
  • PyDitz includes a plugin system for adding new commands.
  • PyDitz currently offers no central public method of bug submission.


You can find installation instructions and a release history on the PyDitz BitBucket page.

Using PyDitz

There are several different ways to use PyDitz:

  1. Treat issue change the same as code change: include it as part of commits, and merge it with changes from other developers, resolving conflicts in the usual manner.
  2. Keep the issue database in the repository but in a separate branch. Issue changes can be managed by your VCS, but is not tied directly to code commits.
  3. Keep the issue database separate and not under VCS at all.

All of these options are supported; the choice of which to use depends on your workflow.

Option #1 is probably most appropriate for the unsynchronized, distributed development, since it allows individual developers to modify issue state with a minimum of hassle. Option #2 is most suitable for synchronized development, as issue state change can be transmitted independently of code change, and can act as a sychronization mechanism. Option #3 is only useful with some other distribution mechanism, like a central web interface.

The PyDitz Data Model

By default, PyDitz includes the bare minimum set of features necessary for open-source development. Features like time spent, priority, assignment of tasks to developers, due dates, etc., are purposely relegated to the plugin system.

A PyDitz project consists of issues, components and releases.


Issues are the fundamental currency of issue tracking. A PyDitz issue is either a feature or a bug, but this distinction currently doesn’t affect anything other than how they’re displayed.

Each issue belongs to exactly one component, and is part of zero or one releases.

Each issues has an exportable id, in the form of 40 random hex characters. This id is “guaranteed” to be unique across all possible issues and developers, present and future. Issue ids are typically not exposed to the user.

Issues also have a non-global, non-exportable name, which is short and human-readable. All PyDitz commands use issue names in addition to issue ids. Issue names (but not issue ids) may change in certain circumstances, e.g., after a drop command.

Issue names can be specified in comments, titles and descriptions, and PyDitz will automatically rewrite them as necessary when they change.


There is always one “general” component, named after the project itself. In the simplest case, this is the only component, and the user is never bothered with the question of which component to assign an issue to.

Components simply provide a way of organizing issues, and have no real functionality. Issues names are derived from the component they’re assigned to.

A release is the primary grouping mechanism for issues. Status commands like status and todo always group issues by release. When a release is 100% complete, it can be marked as released, and its issues will cease appearing in PyDitz status and todo messages.