Repository files navigation

Issue is a command line issue tracker with dead-simple interface, andno-bullshit philosophy.

Issue has only one interface - the cliissue tool written in Python 3.

The command line tool is built around simple actions, e.g. opening, closing or commenting issues.All of basic concepts map to a command:

• issue open "<message>" to open an issue,
• issue close <unique-id> to close an issue,
• issue comment <unique-id> "<comment>" to comment on an issue,

Issue provides machinery for those few things that are really neccessary:

• opening issues,
• listing issues,
• closing issues,
• commenting on issues,
• sharing issues with other programmers,

Notice the wordprogrammers.It is not a tool intended to be used by general audience.

It is created for those people who spend numerous hours a dayin front of a black screen filled with code, shell commands and debugger output.They don't need the distraction of switching to a web-based issue trackerbut still may need to note problems with the code.This program is created for them - to not break their workflow,but to be easily intergrated into it.Written with the UNIX spirit in mind, it does one thing and (hopefully) does it well.

All the extra features are written while keeping in mind that the target group are programmers.For example, there is aissue slug command that generates branch names based on issue messages.

These are the only commands you have to run before you can initialise a repository andstart creating issues:

# set your credentials...$ issue config --global set author.email "john.doe@example.com"$ issue config --global set author.name "John Doe"# initialise the repository$ issue init

And you are ready to run.For more help, you can use:

$ issue help -vc | less -R

This command will give you an exhaustive overview of the commands andoptions.

Issue is written with the intent to keep the workflow optimised, andreduce distractions to minimum.

Consider these steps:

• issue open "Crash on big numbers" - open an issue,
• git checkout -b $(issue slug --git deadbeef) - create new branch usingbranch name generation (or useissue slug -BC deadbeef)
• gdb ./a.out - debug the program,
• vim ... - create a patch,
• git commit -m 'Fix the crash on big numbers' - commit the fix,
• issue close -g <git-commit> deadbeef - close the issue (you can use a Gitcommit hash, orHEAD to specify commit)

Two additional commands to open and close an issue.

Issue provides you with more than justopen andclose commands. This FAQwill provide examples of common tasks that you can perform using the tool.

Thedeadbeef string will be used to provide a placeholder for an issue ID.

$ issue comment deadbeef 'A comment'

If you do not supply the comment text directly on the command line, an$EDITORwill be open for you, with a message reminding you what you wanted to do:

$ issue comment deadbeefA comment# Type a comment.# Lines beginning with '#' will be ignored.## Issue deadbeefd2eece78dbf8f98e357ba0af65f7e180:##  > Dummy issue#  >#  > A dummy issue's description.## vim:ft=gitcommit:#

$ issue ls              # all issues$ issue ls --open       # only open issues$ issue ls --closed     # only closed issues

Issue also provides you with more sphisticated methods of listing issues.

$ issue ls "your" "filter" "terms"

The--open and--closed options also work:

$ issue ls -o "memory"  # List all open issues related to "memory".$ issue ls -c "test"    # List all closed issues related to testing.

You can also filter by time.

List all open issues created during last two weeks, that contain the keyword"deadlock":

$ issue ls -o --since 2weeks "deadlock"

List all issues closed today:

$ issue ls -c --since 8hours

List all open issues created in the previous week:

$ issue ls -o --since 2weeks --until 1week

List all issues with tag "bug" created more than 3 days ago

$ issue ls --until 3days --tag bug

$ issue tag 'bug' deadbeef

This will put a tagbug on the issuedeadbeef. The full example would belike this:

$ issue show deadbeefd2eece78dbf8f98e357ba0af65f7e180issue deadbeefd2eece78dbf8f98e357ba0af65f7e180opened by:    John Doe (john.doe@example.com), on 1970-01-01 23:59:59.000000    Dummy issue$ issue tag bug deadbeefissue deadbeefd2eece78dbf8f98e357ba0af65f7e180opened by:    John Doe (john.doe@example.com), on 1970-01-01 23:59:59.000000tags:         bug    Dummy issue

A tag must be created before it can be assigned to issues. This prevents typosand frustration when looking for issues tagged withdocs and not finding theone accidentally taggeddoca.

$ issue tag new 'tagname'

$ issue tag ls

$ issue show deadbeef

$ issue chain link deadbeef f1eece

This command will "chain" the issuef1eece todeadbeef. This will be visiblein the output ofissue show deadbeef.

An issue cannot be closed until all issues that are chained to it are closed. Inthe example above Issue will not allow closingdeadbeef beforef1eece isclosed.

$ issue statistics

This will give you an overview of the repository:

• how many open and closed issues it has
• the total, average, and median lifetime of open and closed issues
• the total, average, and median lifetime of all issues without the divisioninto open and closed

Issue creates its repository inside a.issue directory. Since it is a hiddenfile any reasonable.gitignore will opt out of tracking it. Here are the rulesyou need to put inside your.gitignore file to enable tracking of the relevantbits of the issue repository:

!.issue.issue/*!.issue/objects.issue/objects/issues/*/*.json

Paste this rules after the.* rule and Git will track issue diffs and commentswithout tracking all the other files that can be crated locally (using less datawhen either cloning or pushing - "yay!" for efficiency).

After that, you can just periodically usegit add .issue and commit changedissues like any other file.

Yeah, typingissue statistics can get old really quick. Lucky you, Issuecommands may be abbreviated (funny that the word meaning "shortened" is a longone). So instead of typingissue statistics you can just typeissue st. Theshortest string that uniquely identifies a command will work.

As another example, instead of usingissue tag new foo you can useissue t n foo.

$ issue slug deadbeefissue-deadbeef-dummy-issue

Then you can either create a command like this one:

$ git checkout -b $(issue sl deadbeef)

...or use the shortcuts built into Issue itself:

$ issue sl -BC deadbeef

$ issue log

The log contains a list of events that happened inside you local repository.This log isnot exchanged between repositories as every developer has theirown log (the fact that Alice checked thedeadbeef issue does not mean thatBob also did and would pollute his log).

$ issue help -vc | less -R

This will give you a long, long wall of text that lists every option and commandthat Issue provides. The-v (or--verbose) is there to enable recursive helpscreen display, and-c enabled colours.

Alternatively, you can get a help screen about just a single command:

$ issue help -c ls

or a even a single option:

$ issue help -c ls --open

Note that using the built-in features for issue distribution is discouraged.They are slow, inefficient, and not really tested. It is much better to justtrack issue repository as a normal directory in your Git repository.

Issue is designed as a distributed system, with apull method for data distribution.A peer must explicitly pull the data and cannot push it.Currently, Issue can use only SSH for issue distribution.

Remote nodes are managed withremote command:

• issue remote set --url <username>@<hostname>:<path> <remote-name> - to set a remote,
• issue remote set --key <key-name> --value <data> <remote-name> - to set additional info for a remote,
• issue remote ls [--verbose] - to list available remote names (include--verbose to display SSH URLs in the report),
• issue remote rm <remote-name> - to remove a remote,

Before peers can fetch data from a node, it mustpack its repository to announce what is available from it.Each node should maintain an up-to-date pack of itself.Pack is updated withissue --pack command.

Obtaining data from a node is simple:

• issue fetch --probe <remote-name> - to probe a remote and display how much data it holds that is locally unavailable,
• issue fetch <remote-name> - to fetch locally unavailable data,

Every node in the network operates as a peer to others, and there is no central one.

Configuration file is located in~/.issueconfig.json.Seesampleconfig.json for a minimal configuration file.

{      "slug.format.default": "@foo"    , "slug.format.foo": "foo-issue-{short_uid}-{slug}"}

To add formatfoo add aslug.format.foo key to your config.Keys available in the format string are:

• short_uid: inserts short UID of the issue
• parent_short_uid: inserts short UID of the parent issue
• slug: inserts slug of the issue

{    "slug.allow_branching_from": [ "master", "devel" ]}

Use theslug.allow_branching_from configuration value to set the branches fromwhich creating new branches is allowed. Issue will complain if you try to createa branch (usingissue sl -B) from a branch not on this list.

Issue is published under the GNU GPL v3 license.Mail me if you would like to use the software under a different license.

Issue requires a recent version of Python 3 (any above 3.6 should be good).

Libraries:

• CLAP: at least0.15.0 (must be installed from Git)
• unidecode: at least1.0.23
• colored: at least1.3.93 (optional; provides colorisation)