distix tutorial
===============

distix is a distributed ticketing system. This is a tutorial for the
command line interface.


Initialise a new ticket repository: `distix init`
-------------------------------------------------

distix keeps all tickets in text files in a git repository. The
repository is created (or at least initialised) with the `distix init`
command:

    distix init my-tickets "These are my tickets"
    cd my-tickets

The first argument to `init` is the directory the repository should be
in. This directory mustn't exist yet. The second argument is a
description of the repository: what is repository meant for?

After you've initialised the repository, it contains some metadata
about the repository:

    .git
    repo.yaml

The `.git` subdirectory is used by git for storing versions of all the
other files. This is needed for distributed and offline operation with
the ticketing system, and for merging and synchronising tickets across
computers.

`repo.yaml` contains some metadata about the repository itself. Most
importantly, it contains the description of the repository you gave
`init`.


Create a new ticket: `distix new`
---------------------------------

To create a new ticket, run a command like this:

    distix new "This is the title of my new ticket"

If all goes well, distix will create a new ticket. The ticket will
have a universally unique identifier (UUID), which is a random 128-bit
number. The ticket will be stored in the directory
`tickets/0234e10813ca44438510c37a7b61abb2`, where
`0234e10813ca44438510c37a7b61abb2` is the hexadecimal representation
of the UUID.

You can use the following command to list all tickets:

    distix list

This will produce output like the following:

    24e885d6e463441baf0fcd76626afa1a distix doesn't invoke editor
    468a9c8545604ce18f1e381fae5e8bac bottle templates are embedded in code
    49001e5d68c649b9886e35513eb24b55 distix lacks a manual page
    8268e49d83ea43a6a362281603d8a7f3 distix show doesn't show the headers of messages
    0234e10813ca44438510c37a7b61abb2 distix home page is useless

Each line shows the UUID of the ticket and its title.

You can restrict the list to only open tickets:

    distix list status!=closed

This will list all tickets, except the ones that have a metadata item
called `status` with a value `closed`.

Writing long UUIDs is somewhat tedious. Remembering them is also not
always easy for humans. distix will, later, allow easier ways to refer
to tickets.


Looking at tickets: `distix show`
---------------------------------

To look at a specific ticket, give a command like this:

    $ distix show 0234e10813ca44438510c37a7b61abb2
    0234e10813ca44438510c37a7b61abb2: distix home page is useless

    * ticket-id: 0234e10813ca44438510c37a7b61abb2
    * title: distix home page is useless

    $ 

This shows the ticket id, and title, and all the key/value metadata
for the ticket. The ticket id and title are stored as key/value pairs,
so the get repeated. (This repetition is not there to make it easier
to learn the id by heart. Honest.)


Setting ticket metadata: `distix set`
-------------------------------------

Each ticket has some key/value pairs. These allow distix to manage
ticket metadata. You can add any pairs you like.

    $ distix set status=triaged 0234e10813ca44438510c37a7b61abb2 
    $ distix show 0234e10813ca44438510c37a7b61abb2
    0234e10813ca44438510c37a7b61abb2: distix home page is useless

    * status: triaged
    * ticket-id: 0234e10813ca44438510c37a7b61abb2
    * title: distix home page is useless

    $ 

Here we added a key `status` with the value `triaged` to the ticket.

distix will interpret some keys in its own way, but ignores all other
keys. The keys it cares about are, at this time:

* `ticket-id`: the UUID of the ticket; you should not change this
* `title`: the ticket title; you may change this if you like
* `status`: the open/close status of the ticket; the value `closed`
  marks a ticket as closed


More?
-----

That's all distix can do right now. This tutorial should, however,
cover more things, such as using git to synchronise, share, and merge
ticket repositories between computers and people. That will be added
once someone figures out a good way to do that.