RepoGrams will help you understand a project's history. It uses a simple visual metaphor to represent a project's history across multiple metrics of interest. It supports metrics like:

• who made commits, how often, and how much code did their commits change
• the number of programming languages used in a project over time
• how often developers changed code across different modules (directories)
• the use of branches in the repository
• and many others!

RepoGrams can help:

• managers to analyze a team's performance and pin-point workflow issues
• developers to understand the workflow and the history of an unfamiliar software project
• researchers in the software engineering community to juxtapose software repositories of multiple projects to select an appropriate set of evaluation targets for a study

For more details about RepoGrams, see our paper:

Comparing Repositories Visually with RepoGrams. Daniel Rozenberg, Ivan Beschastnikh, Fabian Kosmale, Valerie Poser, Heiko Becker, Marc Palyart, Gail Murphy. MSR 2016.

@inproceedings{Rozenberg2016,
  author = {Rozenberg, Daniel and Beschastnikh, Ivan and Kosmale, Fabian and Poser,
            Valerie and Becker, Heiko and Palyart, Marc and Murphy, Gail C.},
  title = {{Comparing Repositories Visually with Repograms}},
  year = {2016},
  url = {https://doi.org/10.1145/2901739.2901768},
  booktitle = {Proceedings of the 13th International Conference on Mining Software Repositories (MSR)},
  pages = {109–120},
}

RepoGrams runs inside a docker image. After cloning the repository, run ./build.sh) in a shell to locally build the image. Use ./run.sh [port-number] (defaults to 1234) and ./stop.sh to start/stop the application.

The following are optional additions to RepoGrams.

You can add example states (pre-configured sets of repositories and corresponding metrics) to your deployment. Add a file called example-states.js to the build/ directory before building the docker image.

See the file examples/example-states.js for an example of an examples set file.

RepoGrams only supports cloning public HTTP and HTTPS repositories, and does not currently support credentials.

You can add extra HTML to the footer of the page by adding it to build/extra-footer.html. This can enable adding scripts such as web analytics.

You can cache a large number of git repositories on the server side by running ./precache.sh [domain-name] [file-with-list-of-repository-urls] where the latter is a text file with one git repository URL per line. This command will load all the repositories into the running docker image's memory. As long as these repositories do not change, they will be served from cache when called in the web application.

Developing inside a docker image is inconvenient. A more convenient way to develop is to deploy RepoGrams locally on your machine.

Start by installing the following packages on your machine. We list the minimum version that works on our development environments. Older versions might still work. If they worked for you please let us know so we can update this list.

• python (3.7.x), python-dev, and python-pip
• python-graph-tool >= 2.2.42
• libgit2-dev >= 0.22.1
• libblas-dev >= 1.2.20110419
• liblapack-dev >= 3.5.0
• libffi-dev >= 3.1
• gfortran >= 4.9.1

In various Linux distributions you may be able to install most (if not all) of these packages using the distro package manager, e.g., sudo apt-get install <package-name> in Debian/Ubuntu. However, if you do so pay careful attention to the versions of the libraries installed, as your Linux distribution's package manager might only contain older versions, in which case you will have to manually install a newer version. Please create an issue or pull request if you believe we forgot to list a dependency.

Create and activate a virtualenv based on Python 3.7.x. Once activated install the requirements.txt inside the virtualenv using pip: pip install -r conf/requirements.txt

Some users reported difficulty installing using the above command line, but managed to install the packages by running pip install <line-from-requirements.txt>, where <line-from-requirements.txt> is each line of requirements.txt one by one.

Copy the python-graph-tool library from the distribution-wide lib directory to the virtualenv. Unfortunately graph-tool is not available on pip. cp -r /usr/lib/python3.7/dist-packages/graph_tool /path/to/venv/lib/python3.7/site-packages/ (the paths on your system might vary)

Run the application with python app/serve.py development (the environment variable PYTHONPATH should be set to the current directory. e.g., PYTHONPATH=. python app/serve.py development.) Point your browser to http://localhost:8090/.

To add a new metric you will have to:

• Create the computation / server-side (Python) file inside app/metrics/. Start by copying _examples.py and modifying it.
• Create the presentation / client-side (JavaScript) file inside app/metrics/. Start by copying _examples.js and modifying it.
• Modify the app/metrics/__init__.py file to register your module. Make sure that you import the metric, not the module containing the metric.

If you would like to get in touch, please contact Ivan Beschastnikh at [email protected]

We published a research paper describing the design and evaluation of RepoGrams. If you are using RepoGrams for research and want a citation that you can use in the paper, here is the bibtex:

@inproceedings{Rozenberg2016,
   author = {Daniel Rozenberg and Ivan Beschastnikh and Fabian Kosmale and Valerie Poser and Heiko Becker and Marc Palyart and Gail Murphy},
   title = {{Comparing Repositories Visually with RepoGrams}},
   booktitle = {MSR 2016, Proceedings of the 2016 International Conference on Mining Software Repositories},
   address = {Austin, TX, USA},
   month = {May~14--15,},
   year = {2016}
}

RepoGrams is released under the GPL.