Getting Started

There are two ways to use PyDitz from the command line: either by running a single command, which PyDitz will run and then exit, or (if no command is given), entering a command loop with a Ditz: prompt. The examples in this guide will use the command loop.

To begin using PyDitz in a project, you will need to initialize an issue database. This can be done explicitly using the init command, or, if entering the command loop, it will be done if needed.

When initializing a database, PyDitz will prompt you for some details about you and your project. You can set global defaults for some of these in your Configuration File. Here’s an example of what happens when you type pyditz in a place with no issue database:

Setting up issue database in .

Your name (default 'Dilbert'): 
Your email (default 'dilbert@cubicle.com'): 
Issue directory (default '.ditz-issues'): 
Project name (default 'doc'): helloworld

Ditz database created in /home/glenn/devel/pyditz/doc

By default, when PyDitz creates a new database in a directory, it writes a .ditz-config file there containing the settings. If you want to change these at any point, you can either manually edit this file, or run the reconfigure command and get prompted for the new settings.

If there’s a .ditz-config file in or above the current directory, that’s what PyDitz uses to find the issue database. This means you can run the pyditz command from subdirectories of your project, and things will work as expected.

PyDitz has quite a few commands available. To see them, you can use the help command. If you give a command name as an argument, you’ll get more detailed help on that command. For example:

Ditz: help

Documented commands (type help <topic>):
========================================
EOF            assign     comment  info     quit           shortlog  unassign 
add            changelog  config   init     reconfigure    show      unclaim  
add_component  claim      drop     ipython  release        start     unclaimed
add_reference  claimed    edit     list     releases       status    validate 
add_release    close      export   log      set_component  stop    
archive        cmds       help     mine     shell          todo    

Ditz: help todo
Command:
   todo -- Generate todo list

Usage:
   todo [RELEASE] [-a]

Arguments:
   RELEASE        Release to display

Options:
   -a, --all      Also show closed issues

You can set up command aliases (i.e., shortcuts) via your Configuration File. If you’re in the PyDitz command loop, you can also use TAB completion on commands.