Github Issues Command Line Interface
Python
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.gitignore
README.rst
git-issues
requirements.txt
setup.py

README.rst

GitHub Issues Command Line Interface

Would you like to avoid using a browser when managing "Issues" for your projects hosted on GitHub? Do you prefer using emacs or vim as your text editor of choice? Do you prefer your entire workflow to remain on the command line when developing? Then the GitHub Issues Command Line Interface may be for you.

All attributes of an "issue" can be viewed and edited right from the command line. In fact inspiration was taken from projects like TicGit-ng and git-issues. However, inlike those projects, which store the issues in a special branch on the Repo, this project uses GitHub's API to store issues on GitHub's servers. Therefore, your users can create and comment on issues on GitHub's nice web interface without the need to install git or work from the command line. At the same time, you can stay in your prefered command line development environment without ever needing a browser to review, edit, label, comment on, or open/close issues.

Note

This is alpha software. Various parts are not fully implemented yet and/or may be buggy. Additionaly, the API (including command line arguments) is subject to change without notice. Consider yourself warned.

Documention

The entire command line interface is documented within the command's help interface. Simply use the -h/--help flag from the command line for usage documentation:

$ git-issues -h

Included in the help is a list of subcommands. You may also get help on each subcommand like this:

$ git-issues subcommand -h

where "subcommand" is replaced with the appropriate subcommand you would like help with.

Workflow

It is expected that the issues command will be run from within a Git repositories' working tree. In fact, an error will be generated if you try to use the command outside of a working three. As long as the repo's "remote" for the "master" branch points to a writable GitHub hosted repo (see Configuration below for specifics), the issues command will read from and write to that repo's issues.

Assuming everything is configured properly, cd into our working tree and view a list of open issues:

$ cd myproject
$ git-issues list

 Num Title                                       Lables
 === =========================================== ==========
   5 Bug in foo                                  bug
   2 Typo in Docs                                docs

Suppose we want to view the new issue someone reported as issue #5 listed above:

$ git-issues show 5

 Issue #5: Bug in foo
 ==========================================================

    State: OPEN
     User: bob
  Created: 2012-05-11T20:06:24Z
 Comments: 0

 ----------------------------------------------------------

 Whenever I pass "bar" to `foo()` it gives me an error.

 ----------------------------------------------------------

Obliviously, the original reporter did not provide enough information. Let's add a comment asking for clarification:

$ git-issues comment --new -m "What error does it give you?" 5

Note that if we wanted to provide a longer comment and perhaps add some formatting, just like Git's commit command, we could have left off the -m/--message flag and the text editor defined by GIT_EDITOR would have been opened for us. Upon saving and closing, the comment would then be forwarded to GitHub.

Now, let's check to see if we have a response to our request for more info:

$ git-issues comments --list 5

 waylan commented [12345678]:
 ===========================================================
 @bob, what error does it give you?

 bob commented [98765432]:
 ===========================================================
 It says "Bad Foo" when I do `foo("bar")`.

After pushing our fix, which included the text "fixed #5" in your commit message, GitHub should have closed the issue automaticaly for us. Lets check:

$ git-issues list

 Num Title                                       Lables
 === =========================================== ==========
   2 Typo in Docs                                docs

Sure enough, Issue #5 is no longer listed as an open issue. Lets make sure and list all closed issues:

$ git-issues list --state closed


 Num Title                                       Lables
 === =========================================== ==========
   5 Bug in foo                                  bug
   4 Some weirdness                              invalid
   3 Silly typo                                  bug
   1 A bad issue description which is long ...   wontfix

Excellant! Now let's look at the alledged typo in the docs (issue #2):

$ git-issues show 2

 Issue #2: Typo in Docs
 ==========================================================

    State: OPEN
     User: Sue
  Created: 2012-05-10T11:34:08Z
 Comments: 0

 ----------------------------------------------------------

 What is this "foo"? My spell checker keeps tripping up on
 it.

 ----------------------------------------------------------

Hmm, err, well, that's not a bug. Guess we need to educate our users:

$ git-issues comment --new -m '"Foo" is sometimes used as a placeholder
name in computer programming or computer-related documentation. See
[Wikipedia](https://en.wikipedia.org/wiki/Foobar) for more info.'

And now we can close the issue manually:

$ git-issues edit --state closed 2

Setup and Installation

Dependencies

The issues command is written in Python and relies on Git's command line interface, so at a minimum the following needs to be installed on your system:

No doubt, some of you may have older versions of python installed on your system. Unfortunately, gh-issues uses some features that were only introduced in Python 2.6 It is not likely that gh-issues will ever work on any Python versions earlier than 2.6.

Additionaly, the following python libraries are needed (and should be installed automaticaly when you install gh-issues):

Configuration

After running pip install gh-issues-cli, the git-issues command should have been installed on your path. If not, use the appropriate means to rectify that on your system.

GitHub's API requires authentication to write data to GitHub (and read from private repos). As the API works over http(s) rather than ssh, we cannot use git's standard authentication methods. The API allows two alternatives:

  • Provide a username and password with every request.
  • Provide an OAuth token with every request.

Because gh-issues is a command line program, there is no long-running-process which can hold the username and password in memory between requests. Therefore, the username and password would need to be provided with every command. While this is possable, it can become rather tedious. Therefore, an OAuth token can be created and stored for later use. To create a token run the following command:

$ git-issues init --global --user myusername

A token will be obtained from Github and stored in your git config. Leave off the --global flag if you want a to set a token for a specific repo only. From this point forward, the token will be used and you will not need to supply a username and password.

Be aware that GitHub appears to only allow one token to be created for the script per user, even if the script it running on a differant system. Therefore, the init subcommand will first check to see if you already have a token associated with your account and the "gh-issues-cli" script. If so, that token is used. If not, a new token is requested.

If you already have a token and would like to manually save the token to your git config, run the following command:

$ git config --global github.token YOURTOKEN

For more information on tokens and how to obtain them, see GitHub's API Documentation.

If, in the future, your token becomes compromised, you can visit our Account Profile on GitHub and "revoke" the token to keep your account secure. The token that you would want to "revoke" should be labeled "gh-issues-cli."

Note

If you push and pull from GitHub over http(s), and you don't want to use an OAuth token, gh-issues will extract your GitHub username from your git config and will only prompt for your password. The workflow becomes very similar to using git over http(s). Be aware that gh-issues requires the password for every command, whereas git over http(s) only requires a password when you push or pull, not for every command (commit, log, status, add, rebase, ...).

License

Copyright (c) 2012, Waylan Limberg
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.