<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.5//EN">
<refentry id="ti">
  <refmeta>
    <refentrytitle>ti</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class="date">March 2011</refmiscinfo>
    <refmiscinfo class="source"></refmiscinfo>
    <refmiscinfo class="title">ticgit issue tracker</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>ti</refname>
    <refpurpose>issue tracking system built on Git</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>ti</command>
      <arg choice="req"><replaceable>COMMAND</replaceable></arg>
      <arg choice="opt"><replaceable>ARGUMENTS</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>

    <para>
      <command>ti</command>, short for ticgit, is an issue tracker based
      on the Git revision control system.  It allows you to store bugs
      in your project in a separate <literal>ticgit</literal> or
      <literal>ticgit-ng</literal> branch of its development repository,
      thereby keeping open issues close to the source without cluttering
      the tree.
    </para>

    <para>
      Every ticket consists of the following information:
    </para>

    <variablelist>

      <varlistentry>
        <term>Title</term>
        <listitem>
          <para>
            A short summary of the problem.  This can be compared to the
            subject of an e-mail or to the first line of a Git commit
            message.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Ticket ID</term>
        <listitem>
          <para>
            The Ticket ID (TicId) is the SHA-1 hash of the file which
            holds the ticket name (which is a normalized form of the
            title including the time of ticket creation and a small
            random number). It is used to uniquely identify a ticket.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Number</term>
        <listitem>
          <para>
            Apart from TicIds, tickets can also be referred to by using
            their number.  This will often be preferred to TicIds when
            using ticgit from the command line (i.e., in everyday work),
            but ticket numbers are not persistent (they change with
            every <literal>ti list</literal> invocation).
          </para>
          <para>
            In the current version of ticgit,
            <literal>ti list</literal> does not show numbers any more,
            but they can still be used (by counting manually).
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>State</term>
        <listitem>
          <para>
            A ticket can either be <literal>open</literal>,
            <literal>resolved</literal>, <literal>invalid</literal> or put
            on <literal>hold</literal>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Assignment</term>
        <listitem>
          <para>
            The e-mail address of the person working on the ticket.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Tag</term>
        <listitem>
          <para>
            A custom label which tells more about the nature of a ticket.
            A typical example is <literal>feature</literal> (not a bug,
            but a feature suggestion). ticgit associates no special
            semantics to tags, you are free to choose them however you
            like.
          </para>
          <para>
            Tickets can have an arbitrary number of tags.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Points</term>
        <listitem>
          <para>
            You can use this integer value to assign some numerical
            value, such as a measure for the importance, to each ticket.
            Again, ticgit does not dictate how to use this field.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Comments</term>
        <listitem>
          <para>
            Comments provide a simple form of communication between bug
            reporters and developers.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>
  </refsect1>

  <refsect1>
    <title>COMMANDS</title>

    <para><command>ti</command> supports the following commands:</para>

    <variablelist>

      <varlistentry>
        <term><literal>list</literal></term>
        <listitem>
          <para>
            List tickets.  By default, only <literal>open</literal> issues
            are shown; to show tickets in other states, use <literal>-s
              STATE</literal>.  You can also select by tag
            (<literal>-t TAG</literal>) or by assignment
            (<literal>-a ADDRESS</literal>).  When running
            <literal>list</literal>, small integer numbers will be
            assigned to all shown tickets; you may use them to refer to
            tickets in other commands until you call
            <literal>list</literal> again.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>state</literal></term>
        <listitem>
          <para>
            Pass a ticket ID and a state specification to set the
            ticket's state information.  You can omit the ticket ID to
            work on the current ticket.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>show</literal></term>
        <listitem>
          <para>
            Show everything known about the specified ticket.  You can
            omit the ticket ID to show the current ticket.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>new</literal></term>
        <listitem>
          <para>
            Create a new ticket.  This will launch an editor to let you
            enter a title, more detailled information about the issue,
            and some tags.  Initially, the ticket will be in the
            <literal>open</literal> state.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>checkout</literal></term>
        <listitem>
          <para>
            Set the current ticket.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>comment</literal></term>
        <listitem>
          <para>
            Add a comment to the ticket specified on the command line.
            If you do not pass one, the current ticket will be used.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>tag</literal></term>
        <listitem>
          <para>
            Pass a ticket ID and a tag name to add a label to an issue.
            You can omit the ticket ID to tag the current ticket.  If
            you use the <literal>-d</literal> option, the tag will be
            removed instead of added.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>assign</literal></term>
        <listitem>
          <para>
            Assign the specified ticket to you (or to the given user,
            when <literal>-u ADDRESS</literal> is given).  If you omit
            the ticket ID, the current ticket will be assigned.
            Otherwise, you can prepend <literal>-c</literal> to the
            ticket ID to perform the <literal>checkout</literal> operation
            after assigning the ticket.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>points</literal></term>
        <listitem>
          <para>
            Pass a ticket ID and some integer to assign a point value to
            the given ticket.  If you only pass a number, this command
            manipulates the current ticket.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>sync</literal></term>
        <listitem>
          <para>
            Synchronize tickets with the remote repository specified on
            the command line.  This uses the underlying push and pull
            command implemented in Git, so you can use your usual named
            remotes.  The default remote is <literal>origin</literal>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>recent</literal></term>
        <listitem>
          <para>
            Get a human-readable changelog of the tickets maintained by
            ticgit.  This command takes its information straight from
            the commit messages of the
            <literal>ticgit(-ng)</literal> branch.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>

    <para>
      These commands show usage information about themselves when passed
      the <literal>--help</literal> option.
    </para>
  </refsect1>

  <refsect1>
    <title>FILES</title>

    <variablelist>
      <varlistentry>
        <term><filename>~/.ticgit/, ~/.ticgit-ng/</filename></term>
        <listitem>
          <para>
            The ticket cache.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>AUTHOR</title>

    <para>
      ticgit is Copyright &copy; 2008 Scott Chacon
      &lt;<email>schacon@gmail.com</email>&gt;.
    </para>

    <para>
      ticgit-ng is Copyright &copy; 2011 Jeff Welling
      &lt;<email>jeff.welling@gmail.com</email>&gt;.
    </para>

    <para>
      This manual page was written by Michael Schutte for the Debian
      GNU/Linux system (but may be used by others).
    </para>
  </refsect1>
</refentry>
<!-- vim: set sw=2 sts=2 et tw=72: -->
