/git-branch-viewer

A Python WSGI viewer of branches in git repositories.

Primary LanguagePythonBSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

git-branch-viewer

Build Status Coverage Status

A Python WSGI viewer of branches in Git repositories. Through a web browser, it allows you to view the branches in a repository, including their status (age, unmerged commits).

Requirements

Installation

  1. Install all the requirements above. Flask can be installed by using easy_install or pip (recommended):

    pip install flask
    
  2. Clone this repository to your web server:

     git clone https://github.com/s3rvac/git-branch-viewer
    
  3. Set up your web server and point it to the git-branch-viewer/git-branch-viewer.wsgi file. A sample configuration for Apache 2.4 with mod_wsgi:

     LoadModule wsgi_module modules/mod_wsgi.so
    
     WSGIScriptAlias /git-branch-viewer /path/to/git-branch-viewer/git-branch-viewer.wsgi
     WSGIDaemonProcess git-branch-viewer user=some_user group=some_group python-path=/path/to/git-branch-viewer
     <Directory /path/to/git-branch-viewer>
             WSGIProcessGroup git-branch-viewer
             WSGIApplicationGroup %{GLOBAL}
             Require all granted
     </Directory>
    
  4. Configure the viewer (see the Configuration section below).

  5. Start/restart your web server.

Usage

Simply open http://your-server.com/git-branch-viewer in your favorite web browser. Depending on your configuration, you should see a list of branches on the given remote in the given repository. For each branch, you can see its name, age, current commit, and commits that have not yet been merged into the master branch. If a branch does not have any unmerged commits, it is marked with a red square (usually, such branches can be removed as they contain nothing that is not already in the master branch).

Configuration

The global (default) configuration is stored in git-branch-viewer/viewer/web/settings/default.cfg. Do NOT edit this file to override the settings. Instead, create a new file local.cfg in the same directory and add the modified settings in there. When the viewer is run, it first loads the default configuration. Then, it loads the local configuration (if any) and overrides the already loaded settings.

You should at least override GIT_REPO_PATH, which tells the viewer which Git repository it should use. Currently, it has to be an absolute path to a cloned repository.

An example of local.cfg:

GIT_REPO_PATH='/path/to/some/cloned/repository'
GIT_BRANCHES_TO_IGNORE = ['master', 'stable']
COMMIT_DETAILS_URL_FMT = 'http://your-server.com/some-app-to-show-commit-details/{}'
UNMERGED_COMMITS_LIMIT = 10

As you can see, the configuration uses Python constructs, such as strings and lists. See default.cfg for all the possible configuration settings, including their description.

Notes

  • The viewer does not perform any repository updates by itself. To keep your repository up to date, you should set up a cronjob:
# Update the cloned repository for git-branch-viewer every 1 minute.
*/1 * * * * git -C /path/to/some/cloned/repository pull --prune

Contribution

Any contributions are welcomed. Notes:

  • Project documentation can be generated by running make docs (you need to have Sphinx installed).
  • The code is covered with unit tests. To run them, execute make tests (you need to have nose installed).
  • Test coverage can be generated by executing make tests-coverage (once again, you need to have nose installed).
  • To ensure that the code complies to PEP8, execute make lint (you need to have flake8 installed).
  • By executing script run-dev-web-server.py, a local web development server is run, which is available on http://localhost:5000. Whenever you modify a source file, the server automatically reloads itself. Moreover, in case of an exception, it prints the whole stack trace to ease the debugging. Warning: Do NOT use this local server in production because it may allow attackers to execute arbitrary code on your server!

See the contents of the Makefile file to all the possible targets.

License

Copyright (c) 2014 Petr Zemek s3rvac@gmail.com and contributors

Distributed under the BSD 3-clause license. See the LICENSE file for more details.