gitsome is hosted on PyPI. The following command will install gitsome:
$ pip install gitsome
You can also install the latest gitsome from GitHub source which can contain changes not yet pushed to PyPI:
$ pip install git+https://github.com/donnemartin/gitsome.git
If you are not installing in a virtualenv, run with sudo:
$ sudo pip install gitsome
Once installed, run the optional gitsome autocompleter with interactive help:
$ gitsome
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 your shell.
Running the gitsome shell will provide you with autocompletion, interactive help, fish-style suggestions, a Python REPL, etc.
It is recommended that you install Python packages in a virtualenv to avoid potential issues with dependencies or permissions.
To view gitsome virtualenv installation instructions, click here.
To properly integrate with GitHub, gitsome must be properly configured:
$ gh configure
View more details in the gh configure section.
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.
You can run gh commands outside of the gitsome shell completer. To enable gh tab completions for this workflow, copy the 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
Displaying the avatar for the gh me and gh user commands will require installing the optional PIL or Pillow dependency.
Windows* and Mac:
$ pip install Pillow
*See the Windows Support section for limitations on the avatar.
Ubuntu users, check out these instructions on askubuntu
- Python 3.4
- Python 3.5
gitsome is powered by xonsh which does not currently support Python 2.x, as discussed in this ticket.
- 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 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.
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.
On Windows, the .gitsomeconfig file can be found in %userprofile%. For example:
C:\Users\dmartin\.gitsomeconfig
If you're interested in contributing to gitsome, run the following commands:
$ git clone https://github.com/donnemartin/gitsome.git
$ pip install -e .
$ pip install -r requirements-dev.txt
$ gitsome
$ gh <command> [param] [options]
Continuous integration details are available on Travis CI.
Code coverage details are available on Codecov.
Run unit tests in your active Python environment:
$ python tests/run_tests.py
Run unit tests with tox on multiple Python environments:
$ tox
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
Contributions are welcome!
Review the Contributing Guidelines for details on how to:
- Submit issues
- Submit pull requests
- click by mitsuhiko
- github_trends_rss by ryotarai
- github3.py by sigmavirus24
- html2text by aaronsw
- img2txt by hit9
- python-prompt-toolkit by jonathanslenders
- requests by kennethreitz
- xonsh by scopatz
Feel free to contact me to discuss any issues, questions, or comments.
My contact info can be found on my GitHub page.
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.