Repository files navigation

AnOfficial Integration for GitHub andGitHub Enterprise.

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

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

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

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

• Improving ease-of-use
• Increasing productivity

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

gitsome includes 29 GitHub integrated commands that work withALL shells:

$ gh <command> [param] [options]

• Quick reference
• General reference

Rungh commands along withGit-Extras andhub commands to unlock even more GitHub integrations!

You can run theoptional shell:

 $ gitsome

to enableautocompletion andinteractive help for the following:

• Git commands
• Git options
• Git branches, tags, etc
• Git-Extras commands
• GitHub integration commands

gitsome autocompletes the following:

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

To enable additional autocompletions, check out theEnabling Bash Completions section.

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

gitsome is powered byxonsh, which supports a Python REPL.

Run Python commands alongside shell commands:

Additionalxonsh features can be found in thexonsh tutorial.

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.

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) toNone.white can appear as light gray on some terminals.

gitsome is available for Mac, Linux, Unix,Windows, andDocker.

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 tocontribute!

• GitHub Integration Commands Syntax
• GitHub Integration Commands Listing
• GitHub Integration Commands Quick Reference
• GitHub Integration Commands Reference in COMMANDS.md
  • gh configure
  • gh create-comment
  • gh create-issue
  • gh create-repo
  • gh emails
  • gh emojis
  • gh feed
  • gh followers
  • gh following
  • gh gitignore-template
  • gh gitignore-templates
  • gh issue
  • gh issues
  • gh license
  • gh licenses
  • gh me
  • gh notifications
  • gh octo
  • gh pull-request
  • gh pull-requests
  • gh rate-limit
  • gh repo
  • gh repos
  • gh search-issues
  • gh search-repos
  • gh starred
  • gh trending
  • gh user
  • gh view
• Option: View in a Pager
• Option: View in a Browser

• Installation
  • Pip Installation
  • Virtual Environment Installation
  • Running as a Docker Container
  • Running thegh configure Command
    • For GitHub Enterprise Users
  • Enabling Bash Completions
  • Enablinggh Tab Completions Outside ofgitsome
    • For Zsh Users
  • Optional: InstallingPIL orPillow
  • Supported Python Versions
  • Supported Platforms
  • Windows Support
• Developer Installation
  • Continuous Integration
  • Unit Tests and Code Coverage
  • Documentation

• Contributing
• Credits
• Contact Info
• License

Usage:

$ gh <command> [param] [options]

  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.

See theGitHub Integration Commands Reference in COMMANDS.md for adetailed discussion of all GitHub integration commands, parameters, options, and examples.

Check out the next section for aquick reference.

To properly integrate with GitHub, you must first configuregitsome:

$ gh configure

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

$ gh configure -e

$ gh feed

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

$ gh feed donnemartin -p

$ gh feed donnemartin/gitsome -p

$ gh notifications

View all pull requests for your repos:

$ gh pull-requests

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 thegh issues reference inCOMMANDS.md.

$ gh starred "repo filter"

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 thesearching issues reference.

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 thesearching repos reference.

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

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]

View an issue:

$ gh issue donnemartin/saws/1

View a pull request:

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

List all available.gitignore templates:

$ gh gitignore-templates

Set up your.gitignore:

$ gh gitignore-template Python > .gitignore

List all availableLICENSE templates:

$ gh licenses

Set up your orLICENSE:

$ gh license MIT > LICENSE

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

$ gh octo [say]

$ gh user octocat

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

$ gh me

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

Manygh 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

Manygh 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

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

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

Note, you can combinegitsome with other utilities such asGit-Extras.

gitsome is hosted onPyPI. The following command will installgitsome:

$ pip3 install gitsome

You can also install the latestgitsome 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 avirtualenv, you might need to run withsudo:

$ sudo pip3 install gitsome

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

$ sudo -H pip3 install gitsome

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

For example, Ubuntu users can run:

$ sudo apt-get install python3-pip

See thisticket for more details.

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

If you are a Windows user or if you would like more details onvirtualenv, check out thisguide.

Installvirtualenv andvirtualenvwrapper:

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

Create agitsomevirtualenv and installgitsome:

$ mkvirtualenv gitsome$ pip3 install gitsome

If thepip 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 callingmkvirtualenv:

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

If you want to activate thegitsomevirtualenv again later, run:

$ workon gitsome

To deactivate thegitsomevirtualenv, run:

$ deactivate

You can run gitsome in a Docker container to avoid installing Python andpip3 locally. To install Docker check out theofficial 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 .

Once installed, run the optionalgitsome autocompleter with interactive help:

$ gitsome

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

Run GitHub-integrated commands:

$ gh <command> [param] [options]

Note: Running thegitsome shell is not required to executegh commands. Afterinstallinggitsome you can rungh commands from any shell.

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

$ gh configure

Run with the-e/--enterprise flag:

$ gh configure -e

View more details in thegh configure section.

By default,gitsome looks at the followinglocations 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 restartgitsome for the changes to take effect.

You can rungh commands outside of thegitsome shell completer. To enablegh tab completions for this workflow, copy thegh_complete.sh file locally.

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

$ source /path/to/gh_complete.sh

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

source /path/to/gh_complete.sh

Reload yourbashrc:

$ source ~/.bashrc

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

$ . ~/.bashrc

zsh includes a module which is compatible with bash completions.

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

autoload bashcompinitbashcompinitsource /path/to/gh_complete.sh

Reload yourzshrc:

 $ source ~/.zshrc

Displaying the avatar for thegh me andgh user commands will require installing the optionalPIL orPillow dependency.

Windows* and Mac:

$ pip3 install Pillow

*See theWindows Support section for limitations on the avatar.

Ubuntu users, check out theseinstructions on askubuntu

• Python 3.4
• Python 3.5
• Python 3.6
• Python 3.7

gitsome is powered byxonsh which does not currently support Python 2.x, as discussed in thisticket.

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

gitsome has been tested on Windows 10 withcmd andcmder.

Although you can use the standard Windows command prompt, you'll probably have a better experience with eithercmder orconemu.

The commandsgh user andgh me will always have the-t/--text_avatar flag enabled, sinceimg2txt does not support the ansi avatar on Windows.

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

C:\Users\dmartin\.gitsomeconfig

If you're interested in contributing togitsome, 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]

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

$ sudo apt-get install python3-pip

See thisticket for more details.

Continuous integration details are available onTravis CI.

Run unit tests in your active Python environment:

$ python tests/run_tests.py

Run unit tests withtox on multiple Python environments:

$ tox

Source code documentation will soon be available onReadthedocs.org. Check out thesource docstrings.

Run the following to build the docs:

$ scripts/update_docs.sh

Contributions are welcome!

Review theContributing Guidelines for details on how to:

• Submit issues
• Submit pull requests

• click bymitsuhiko
• github_trends_rss byryotarai
• github3.py bysigmavirus24
• html2text byaaronsw
• img2txt byhit9
• python-prompt-toolkit byjonathanslenders
• requests bykennethreitz
• xonsh byscopatz

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

My contact info can be found on myGitHub 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 MartinLicensed 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.0Unless required by applicable law or agreed to in writing, softwaredistributed 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 andlimitations under the License.