To install git-upstream from pypi, run:

pip install --user git-upstream

Alternatively, the current release can be installed system-wide from pypi:

sudo pip install git-upstream

Installing directly from source is possible, first clone and then install using pip:

git clone
cd git-upstream
pip install .


git clone
cd git-upstream
python install

Or alternatively:

git clone
cd git-upstream
easy_install .

If you want command line completion (using tab), install the provided “bash completion” file

mkdir ~/bin && cp ./bash_completion/git-upstream ~/bin
echo ". ~/bin/git-upstream" >> ~/.bash_profile

Verify your installation.

pip show git-upstream
Name: git-upstream
Version: 0.12.1
Summary: git tool to help manage upstream repositories
Author: Darragh Bailey
License: Apache License (2.0)
Location: /home/<username>/.local/lib/python2.7/site-packages
Requires: argcomplete, pbr, six, GitPython

git-upstream --help
usage: git-upstream [--version] [-h] [-q | -v] <command> ...


Installing for Development

A virtual environment is recommended for development. For example, git-upstream may be installed from the top level directory:

virtualenv .venv
source .venv/bin/activate
pip install -r test-requirements.txt -e .

Generating Documentation

Documentation is included in the doc folder. To generate docs locally execute the command:

tox -e docs

The generated documentation is then available under doc/build/html/index.html.

  • Note: When behind a proxy it is necessary to use TOX_TESTENV_PASSENV to pass any proxy settings for this test to be able to check links are valid.

Unit Tests

Unit tests have been included and are in the git_upstream/tests folder. Many unit tests samples are included as example scenarios in our documentation to help explain how git-upstream handles various use cases. To run the unit tests, execute the command:

tox -e py34,py27
  • Note: View tox.ini to run tests on other versions of Python, generating the documentation and additionally for any special notes on building one of the scenarios to allow direct inspection and manual execution of git-upstream with various scenarios.

The unit tests can in many cases be better understood as being closer to functional tests.

Test Coverage

To measure test coverage, execute the command:

tox -e cover