Github url

gitsome

by donnemartin

donnemartin /gitsome

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

6.8K Stars 386 Forks Last release: over 1 year ago (0.8.0) Other 1.0K Commits 5 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

An Official Integration for GitHub and GitHub Enterprise.

gitsome

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]
</command>

Run

gh

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

Imgur

Git and GitHub Autocompleter With Interactive Help

You can run the optional shell:

$ gitsome

to enable autocompletion and interactive help for the following:

Imgur

Imgur

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.

Imgur

Fish-Style Auto-Suggestions

gitsome

supports Fish-style auto-suggestions. Use the

right arrow

key to complete a suggestion.

Imgur

Python REPL

gitsome

is powered by [

xonsh

](https://github.com/scopatz/xonsh), which supports a Python REPL.

Run Python commands alongside shell commands:

Imgur

Additional

xonsh

features can be found in the [

xonsh tutorial

](http://xon.sh/tutorial.html).

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.

Imgur

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.

Imgur

Available Platforms

gitsome

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

TODO

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!

Index

GitHub Integration Commands

Installation and Tests

Misc

GitHub Integration Commands Syntax

Usage:

$ gh <command> [param] [options]
</command>

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: COMMANDS.md

See the GitHub Integration Commands Reference in COMMANDS.md 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

Imgur

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

Imgur

Listing A Repo's Activity Feed

$ gh feed donnemartin/gitsome -p

Imgur

Listing Notifications

$ gh notifications

Imgur

Listing Pull Requests

View all pull requests for your repos:

$ gh pull-requests

Imgur

Filtering Issues

View all open issues where you have been mentioned:

$ gh issues --issue\_state open --issue\_filter mentioned

Imgur

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

](https://github.com/donnemartin/gitsome/blob/master/COMMANDS.md#gh-issues) reference in COMMANDS.md.

Filtering Starred Repos

$ gh starred "repo filter"

Imgur

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

Imgur

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

Imgur

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]

Imgur

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]

Imgur

The

issue

command

View an issue:

$ gh issue donnemartin/saws/1

Imgur

The

pull-request

command

View a pull request:

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

Imgur

Setting Up

.gitignore

List all available

.gitignore

templates:

$ gh gitignore-templates

Imgur

Set up your

.gitignore

:

$ gh gitignore-template Python \> .gitignore

Imgur

Setting Up

LICENSE

List all available

LICENSE

templates:

$ gh licenses

Imgur

Set up your or

LICENSE

:

$ gh license MIT \> LICENSE

Imgur

Summoning Octocat

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

$ gh octo [say]

Imgur

Viewing Profiles

Viewing A User's Profile

$ gh user octocat

Imgur

Viewing Your Profile

View your profile with the

gh user [YOUR\_USER\_ID]

command or with the following shortcut:

$ gh me

Imgur

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.

Usage:

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

Option: View in a Browser

Many

gh

commands support a

-b/--browser

option that displays results in your default browser instead of your terminal.

Usage:

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

See the COMMANDS.md 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._

Installation

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+https://github.com/donnemartin/gitsome.git

If you are not installing in a

virtualenv

, you might need to run with

sudo

:

$ sudo pip3 install gitsome

pip3

Depending on your setup, you might also want to run

pip3

with the [

-H flag

](http://stackoverflow.com/a/28619739):

$ 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

](http://docs.python-guide.org/en/latest/dev/virtualenvs/) 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/virtualenvwrapper.sh

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 \ mariolet/gitsome

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 \ mariolet/gitsome"

To build the Docker image from sources:

$ git clone https://github.com/donnemartin/gitsome.git $ 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]
</command>

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

:

$BASH\_COMPLETIONS.append('/usr/local/etc/my\_bash\_completion.d/completion.bash')

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 [

gh\_complete.sh

](https://github.com/donnemartin/gitsome/blob/master/scripts/gh_complete.sh) file locally.

Let bash know completion is available for the

gh

command within your current session:

$ source /path/to/gh\_complete.sh

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

bashrc

file:

source /path/to/gh\_complete.sh

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 [

gh\_complete.sh

](https://github.com/donnemartin/gitsome/blob/master/scripts/gh_complete.sh) file as above and append the following to your

.zshrc

:

autoload bashcompinit bashcompinit source /path/to/gh\_complete.sh

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
  • Python 3.7
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.

Imgur

Text Only Avatar

The commands [

gh user

](https://github.com/donnemartin/gitsome/blob/master/COMMANDS.md#gh-user) and [

gh me

](https://github.com/donnemartin/gitsome/blob/master/COMMANDS.md#gh-me) will always have the

-t/--text\_avatar

flag enabled, since [

img2txt

](https://github.com/donnemartin/gitsome/blob/master/#credits) does not support the ansi avatar on Windows.

Config File

On Windows, the

.gitsomeconfig

file can be found in

%userprofile%

. For example:

C:\Users\dmartin\.gitsomeconfig

Developer Installation

If you're interested in contributing to

gitsome

, run the following commands:

$ git clone https://github.com/donnemartin/gitsome.git $ cd gitsome $ pip3 install -e . $ pip3 install -r requirements-dev.txt $ gitsome $ gh <command> [param] [options]
</command>

pip3

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\_tests.py

Run unit tests with tox on multiple Python environments:

$ tox

Documentation

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

Run the following to build the docs:

$ scripts/update\_docs.sh

Contributing

Contributions are welcome!

Review the Contributing Guidelines for details on how to:

  • Submit issues
  • Submit pull requests

Credits

Contact Info

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

My contact info can be found on my GitHub page.

License

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).

License

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 http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.