Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here


A supercharged Git/GitHub command line interface (CLI). An official integration for GitHub and GitHub Enterprise:

Subscribe to updates I use gitsome

Statistics on gitsome

Number of watchers on Github 5564
Number of open issues 35
Average time to close an issue 8 days
Main language Python
Average time to merge a PR 1 day
Open pull requests 12+
Closed pull requests 0+
Last commit about 2 years ago
Repo Created almost 4 years ago
Repo Last Updated almost 2 years ago
Size 863 KB
Organization / Authordonnemartin
Latest Release0.7.0
Page Updated
Do you use gitsome? Leave a review!
View open issues (35)
View gitsome activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating gitsome for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

An Official Integration for GitHub and GitHub Enterprise.


Build Status PyPI version PyPI License

Why gitsome?

The Git Command Line

Although the standard Git command line is a great tool to manage your Git-powered repos, it can be tough to remember the usage of:

  • 150+ porcelain and plumbing commands
  • Countless command-specific options
  • Resources such as tags and branches

The Git command line does not integrate with GitHub, forcing you to toggle between command line and browser.

gitsome - A Supercharged Git/GitHub CLI With Autocomplete

gitsome aims to supercharge your standard git/shell interface by focusing on:

  • Improving ease-of-use
  • Increasing productivity

Deep GitHub Integration

Not all GitHub workflows work well in a terminal; gitsome attempts to target those that do.

gitsome includes 29 GitHub integrated commands that work with ALL shells:

$ gh <command> [param] [options]

Run gh commands along with Git-Extras and hub commands to unlock even more GitHub integrations!


Git and GitHub Autocompleter With Interactive Help

You can run the optional shell:

 $ gitsome

to enable autocompletion and interactive help for the following:



General Autocompleter

gitsome autocompletes the following:

  • Shell commands
  • Files and directories
  • Environment variables
  • Man pages
  • Python

To enable additional autocompletions, check out the Enabling Bash Completions section.


Fish-Style Auto-Suggestions

gitsome supports Fish-style auto-suggestions. Use the right arrow key to complete a suggestion.


Python REPL

gitsome is powered by xonsh, which supports a Python REPL.

Run Python commands alongside shell commands:


Additional xonsh features can be found in the xonsh tutorial.

Command History

gitsome keeps track of commands you enter and stores them in ~/.xonsh_history.json. Use the up and down arrow keys to cycle through the command history.


Customizable Highlighting

You can control the ansi colors used for highlighting by updating your ~/.gitsomeconfig file.

Color options include:

'black', 'red', 'green', 'yellow',
'blue', 'magenta', 'cyan', 'white'

For no color, set the value(s) to None. white can appear as light gray on some terminals.


Available Platforms

gitsome is available for Mac, Linux, Unix, Windows, and Docker.


Not all GitHub workflows work well in a terminal; gitsome attempts to target those that do.

  • Add additional GitHub API integrations

gitsome is just getting started. Feel free to contribute!


GitHub Integration Commands

Installation and Tests


GitHub Integration Commands Syntax


$ gh <command> [param] [options]

GitHub Integration Commands Listing

  configure            Configure gitsome.
  create-comment       Create a comment on the given issue.
  create-issue         Create an issue.
  create-repo          Create a repo.
  emails               List all the user's registered emails.
  emojis               List all GitHub supported emojis.
  feed                 List all activity for the given user or repo.
  followers            List all followers and the total follower count.
  following            List all followed users and the total followed count.
  gitignore-template   Output the gitignore template for the given language.
  gitignore-templates  Output all supported gitignore templates.
  issue                Output detailed information about the given issue.
  issues               List all issues matching the filter.
  license              Output the license template for the given license.
  licenses             Output all supported license templates.
  me                   List information about the logged in user.
  notifications        List all notifications.
  octo                 Output an Easter egg or the given message from Octocat.
  pull-request         Output detailed information about the given pull request.
  pull-requests        List all pull requests.
  rate-limit           Output the rate limit.  Not available for Enterprise.
  repo                 Output detailed information about the given filter.
  repos                List all repos matching the given filter.
  search-issues        Search for all issues matching the given query.
  search-repos         Search for all repos matching the given query.
  starred              Output starred repos.
  trending             List trending repos for the given language.
  user                 List information about the given user.
  view                 View the given index in the terminal or a browser.

GitHub Integration Commands Reference:

See the GitHub Integration Commands Reference in for a detailed discussion of all GitHub integration commands, parameters, options, and examples.

Check out the next section for a quick reference.

GitHub Integration Commands Quick Reference

Configuring gitsome

To properly integrate with GitHub, you must first configure gitsome:

$ gh configure

For GitHub Enterprise users, run with the -e/--enterprise flag:

$ gh configure -e

Listing Feeds

Listing Your News Feed

$ gh feed


Listing A User's Activity Feed

View your activity feed or another user's activity feed, optionally through a pager with -p/--pager. The pager option is available for many commands.

$ gh feed donnemartin -p


Listing A Repo's Activity Feed

$ gh feed donnemartin/gitsome -p


Listing Notifications

$ gh notifications


Listing Pull Requests

View all pull requests for your repos:

$ gh pull-requests


Filtering Issues

View all open issues where you have been mentioned:

$ gh issues --issue_state open --issue_filter mentioned


View all issues, filtering for only those assigned to you, regardless of state (open, closed):

$ gh issues --issue_state all --issue_filter assigned

For more information about the filter and state qualifiers, visit the gh issues reference in

Filtering Starred Repos

$ gh starred "repo filter"


Searching Issues and Repos

Searching Issues

Search issues that have the most +1s:

$ gh search-issues "is:open is:issue sort:reactions-+1-desc" -p


Search issues that have the most comments:

$ gh search-issues "is:open is:issue sort:comments-desc" -p

Search issues with the help wanted tag:

$ gh search-issues "is:open is:issue label:\"help wanted\"" -p

Search issues that have your user name tagged @donnemartin:

$ gh search-issues "is:issue donnemartin is:open" -p

Search all your open private issues:

$ gh search-issues "is:open is:issue is:private" -p

For more information about the query qualifiers, visit the searching issues reference.

Searching Repos

Search all Python repos created on or after 2015, with >= 1000 stars:

$ gh search-repos "created:>=2015-01-01 stars:>=1000 language:python" --sort stars -p


For more information about the query qualifiers, visit the searching repos reference.

Listing Trending Repos and Devs

View trending repos:

$ gh trending [language] [-w/--weekly] [-m/--monthly] [-d/--devs] [-b/--browser]


View trending devs (devs are currently only supported in browser):

$ gh trending [language] --devs --browser

Viewing Content

The view command

View the previously listed notifications, pull requests, issues, repos, users etc, with HTML nicely formatted for your terminal, or optionally in your browser:

$ gh view [#] [-b/--browser]


The issue command

View an issue:

$ gh issue donnemartin/saws/1


The pull-request command

View a pull request:

$ gh pull-request donnemartin/awesome-aws/2


Setting Up .gitignore

List all available .gitignore templates:

$ gh gitignore-templates


Set up your .gitignore:

$ gh gitignore-template Python > .gitignore


Setting Up LICENSE

List all available LICENSE templates:

$ gh licenses


Set up your or LICENSE:

$ gh license MIT > LICENSE


Summoning Octocat

Call on Octocat to say the given message or an Easter egg:

$ gh octo [say]


Viewing Profiles

Viewing A User's Profile

$ gh user octocat


Viewing Your Profile

View your profile with the gh user [YOUR_USER_ID] command or with the following shortcut:

$ gh me


Creating Comments, Issues, and Repos

Create a comment:

$ gh create-comment donnemartin/gitsome/1 -t "hello world"

Create an issue:

$ gh create-issue donnemartin/gitsome -t "title" -b "body"

Create a repo:

$ gh create-repo gitsome

Option: View in a Pager

Many gh commands support a -p/--pager option that displays results in a pager, where available.


$ gh <command> [param] [options] -p
$ gh <command> [param] [options] --pager

Option: View in a Browser

Many gh commands support a -b/--browser option that displays results in your default browser instead of your terminal.


$ gh <command> [param] [options] -b
$ gh <command> [param] [options] --browser

See the for a detailed listing of all GitHub integration commands, parameters, options, and examples.

Having trouble remembering these commands? Check out the handy autocompleter with interactive help to guide you through each command.

Note, you can combine gitsome with other utilities such as Git-Extras.


Pip Installation

PyPI version PyPI

gitsome is hosted on PyPI. The following command will install gitsome:

$ pip3 install gitsome

You can also install the latest gitsome from GitHub source which can contain changes not yet pushed to PyPI:

$ pip3 install git+

If you are not installing in a virtualenv, you might need to run with sudo:

$ sudo pip3 install gitsome


Depending on your setup, you might also want to run pip3 with the -H flag:

$ sudo -H pip3 install gitsome

For most linux users, pip3 can be installed on your system using the python3-pip package.

For example, Ubuntu users can run:

$ sudo apt-get install python3-pip

See this ticket for more details.

Virtual Environment Installation

You can install Python packages in a virtualenv to avoid potential issues with dependencies or permissions.

If you are a Windows user or if you would like more details on virtualenv, check out this guide.

Install virtualenv and virtualenvwrapper:

$ pip3 install virtualenv
$ pip3 install virtualenvwrapper
$ export WORKON_HOME=~/.virtualenvs
$ source /usr/local/bin/

Create a gitsome virtualenv and install gitsome:

$ mkvirtualenv gitsome
$ pip3 install gitsome

If the pip install does not work, you might be running Python 2 by default. Check what version of Python you are running:

$ python --version

If the call above results in Python 2, find the path for Python 3:

$ which python3  # Python 3 path for mkvirtualenv's --python option

Install Python 3 if needed. Set the Python version when calling mkvirtualenv:

$ mkvirtualenv --python [Python 3 path from above] gitsome
$ pip3 install gitsome

If you want to activate the gitsome virtualenv again later, run:

$ workon gitsome

To deactivate the gitsome virtualenv, run:

$ deactivate

Running as a Docker Container

You can run gitsome in a Docker container to avoid installing Python and pip3 locally. To install Docker check out the official Docker documentation.

Once you have docker installed you can run gitsome:

$ docker run -ti --rm mariolet/gitsome

You can use Docker volumes to let gitsome access your working directory, your local .gitsomeconfig and .gitconfig:

$ docker run -ti --rm -v $(pwd):/src/              \
   -v ${HOME}/.gitsomeconfig:/root/.gitsomeconfig  \
   -v ${HOME}/.gitconfig:/root/.gitconfig          \

If you are running this command often you will probably want to define an alias:

$ alias gitsome="docker run -ti --rm -v $(pwd):/src/              \
                  -v ${HOME}/.gitsomeconfig:/root/.gitsomeconfig  \
                  -v ${HOME}/.gitconfig:/root/.gitconfig          \

To build the Docker image from sources:

$ git clone
$ cd gitsome
$ docker build -t gitsome .

Starting the gitsome Shell

Once installed, run the optional gitsome autocompleter with interactive help:

$ gitsome

Running the optional gitsome shell will provide you with autocompletion, interactive help, fish-style suggestions, a Python REPL, etc.

Running gh Commands

Run GitHub-integrated commands:

$ gh <command> [param] [options]

Note: Running the gitsome shell is not required to execute gh commands. After installing gitsome you can run gh commands from any shell.

Running the gh configure Command

To properly integrate with GitHub, gitsome must be properly configured:

$ gh configure

For GitHub Enterprise Users

Run with the -e/--enterprise flag:

$ gh configure -e

View more details in the gh configure section.

Enabling Bash Completions

By default, gitsome looks at the following locations to enable bash completions.

To add additional bash completions, update the ~/.xonshrc file with the location of your bash completions.

If ~/.xonshrc does not exist, create it:

$ touch ~/.xonshrc

For example, if additional completions are found in /usr/local/etc/my_bash_completion.d/completion.bash, add the following line in ~/.xonshrc:


You will need to restart gitsome for the changes to take effect.

Enabling gh Tab Completions Outside of gitsome

You can run gh commands outside of the gitsome shell completer. To enable gh tab completions for this workflow, copy the file locally.

Let bash know completion is available for the gh command within your current session:

$ source /path/to/

To enable tab completion for all terminal sessions, add the following to your bashrc file:

source /path/to/

Reload your bashrc:

$ source ~/.bashrc

Tip: . is the short form of source, so you can run this instead:

$ . ~/.bashrc

For Zsh Users

zsh includes a module which is compatible with bash completions.

Download the file as above and append the following to your .zshrc:

autoload bashcompinit
source /path/to/

Reload your zshrc:

 $ source ~/.zshrc

Optional: Installing PIL or Pillow

Displaying the avatar for the gh me and gh user commands will require installing the optional PIL or Pillow dependency.

Windows* and Mac:

$ pip3 install Pillow

*See the Windows Support section for limitations on the avatar.

Ubuntu users, check out these instructions on askubuntu

Supported Python Versions

  • Python 3.4
  • Python 3.5

Python 3.6 is not currently supported. See this ticket for more information.

gitsome is powered by xonsh which does not currently support Python 2.x, as discussed in this ticket.

Supported Platforms

  • Mac OS X
    • Tested on OS X 10.10
  • Linux, Unix
    • Tested on Ubuntu 14.04 LTS
  • Windows
    • Tested on Windows 10

Windows Support

gitsome has been tested on Windows 10 with cmd and cmder.

Although you can use the standard Windows command prompt, you'll probably have a better experience with either cmder or conemu.


Text Only Avatar

The commands gh user and gh me will always have the -t/--text_avatar flag enabled, since img2txt does not support the ansi avatar on Windows.

Config File

On Windows, the .gitsomeconfig file can be found in %userprofile%. For example:


Developer Installation

If you're interested in contributing to gitsome, run the following commands:

$ git clone
$ cd gitsome
$ pip3 install -e .
$ pip3 install -r requirements-dev.txt
$ gitsome
$ gh <command> [param] [options]


If you get an error while installing saying that you need Python 3.4+, it could be because your pip command is configured for an older version of Python. To fix this issue, it is recommended to install pip3:

$ sudo apt-get install python3-pip

See this ticket for more details.

Continuous Integration

Build Status

Continuous integration details are available on Travis CI.

Unit Tests and Code Coverage

Run unit tests in your active Python environment:

$ python tests/

Run unit tests with tox on multiple Python environments:

$ tox


Source code documentation will soon be available on Check out the source docstrings.

Run the following to build the docs:

$ scripts/


Contributions are welcome!

Review the Contributing Guidelines for details on how to:

  • Submit issues
  • Submit pull requests


Contact Info

Feel free to contact me to discuss any issues, questions, or comments.

My contact info can be found on my GitHub page.


I am providing code and resources in this repository to you under an open source license. Because this is my personal repository, the license you receive to my code and resources is from me and not my employer (Facebook).


Copyright 2016 Donne Martin

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.
gitsome open issues Ask a question     (View All Issues)
  • over 3 years Simultaneous GH and GHE support
  • over 3 years Release 0.7.0
  • over 3 years Git autocomplete stopped working
  • over 3 years Add hub autocompletions and interactive help
  • over 3 years customize prompt
  • over 3 years Provide man pages
  • over 3 years Provide single lined listings
  • over 3 years Use current .git as default
  • over 3 years Refactor conversion code of None to '' introduced in #40 and #49
  • almost 4 years oh-my-zsh support
  • almost 4 years option to preserve color on pipe
  • almost 4 years Xonsh dependency
  • almost 4 years Can not access to a private repo with a personal access tokens
  • almost 4 years Support native iTerm 2 images
  • almost 4 years Fish shell support
  • almost 4 years Linux dotfiles, XDG Base Directory
  • almost 4 years Gitlab support
gitsome open pull requests (View All Pulls)
  • Support two factor authentication.
  • Changed prompt-toolkit version & updated README
  • List dependencies in instead of embedding
  • Only store password in config for GitHub Enterprise (due to Enterprise limitations)
  • Refactor conversion of None to empty introduced in #49 and #40
  • Fix viewing HTML contents in the terminal for GitHub Enterprise users
  • Update config path to comply with XDG Base Directory spec
  • Add single line display mode to `gh issues`
  • Reactive python 3.6 in gitsome
  • Configurable prompt
  • Refactor user input and add system exit if user interrupts input
  • [WIP] Upgrade to prompt_toolkit 2.0.
gitsome list of languages used
gitsome latest release notes
0.7.0 0.7.0


0.7.0 (2017-03-26)


  • #99 - Add Dockerfile to run gitsome in a Docker container, by l0rd and larson004.

Bug Fixes

  • #67 - Fix gh_issues typo in the README, by srisankethu.
  • #69 - Fix --issue_filter typo for gh_issues command in
  • #80 - Fix path for auto completions in README.
  • #92 - Fix viewing HTML contents in the terminal for GitHub Enterprise users, by dongweiming.
  • #97 - Fix error hint from gh gitignores to gh gitignore-templates, by zYeoman.
  • #116 - Fix gh trending command resulting in an error.


  • #58 - Tweak README intro, add logo.
  • #74 - Add link to official GitHub integration page in README.
  • #79 - Only store password in config for GitHub Enterprise (due to Enterprise limitations), by nttibbetts.
  • #86 - Update dependency info for uritemplate.
  • #89 - Fix a bug listing info on repos without a desc field, by SanketDG.
  • #98 - Prefer GitHub Enterprise token before password.
  • #104 - Update install instructions to use pip3.
  • #111 - Add note about current Python 3.6 incompatibility.
  • #115 - Set current Python support to 3.4 and 3.5.


0.6.0 (2016-05-29)


  • #3 - Add GitHub Enterprise support.
  • #33 - Revamp the info shown with the gh feed command.

Bug Fixes

  • #30 - Fix a typo in the pip3 install instructions.
  • #39 - Fix gh feed -pr/--private flag in docs.
  • #40 - Fix create-issue NoneType error if no -b/--body is specified.
  • #46 - Fix gh view with the -b/--browser option only working for repos, not for issues or PRs.
  • #48 - Fix create-repo NoneType error if no -d/--description is specified.
  • #54 - Update to prompt-toolkit 1.0.0, which includes performance improvements (especially noticeable on Windows) and bug fixes.
  • Fix Config docstrings.


  • #26, #32 - Add copyright notices for third party libraries.
  • #44, #53 - Update packaging dependencies based on semantic versioning.
  • Tweak README intro.


0.5.0 (2016-05-15)


  • #12 - Allow 2FA-enabled users to log in with a password + 2FA code. Previously 2FA-enabled users could only log in with a personal access token. Also includes an update of login prompts to improve clarity.

Bug Fixes

  • #16, #28 - Fix typos in README.
  • #18 - Fix dev install instructions in README.
  • #24 - Fix style guide broken link in CONTRIBUTING.


  • #1 - Add Codecov coverage testing status to README.
  • #2 - Add note about enabling Zsh completions to README.
  • #4 - Add note about using pip3 to README.
  • #5 - Decrease speed of README gif.
  • #6 - Update url for click.
  • #20 - Add note about enabling more completions to README.
  • #21 - Bump up prompt-toolkit version from 0.51 to 0.52.
  • #26 - Add xonsh copyright notice to LICENSE.
  • #32 - Add, html2text, and img2txt copyright notices to LICENSE.
  • Update installation instructions in README.
  • Update color customization discussion in README.
Other projects in Python