git-big-picture 0.10.1

A Small Example

Imagine the following Graph:

         0.1.1   0.1.2
           |       |
0.0    G---H---I---J---K---L---M maint
 |    /
 A---B---C---D---E---F master
     |    \         /
    0.1    N---O---P topic

Where the following commits have Branches and Tags:

A -> 0.0
B -> 0.1
F -> master
H -> 0.1.1
J -> 0.1.2
M -> maint
P -> topic

The reduced graph of interesting commits would be:

      H---J---M
     /
A---B---F
     \ /
      P

But since the commits would be labeled with their refs, it would look more like (within the limits of ASCII art):

      0.1.1---0.1.2---maint
     /
0.0---0.1---master
        \     /
         topic

Demo Video

Chuwei Lu has made a youtube video showing how to use git-big-picture:

https://www.youtube.com/watch?v=H7w7JWSy3oc&feature=youtu.be

Screenshots

Courtesy of Graphviz, git-big-picture can output nice images.

Here is the original repository from the example above:

And here is the reduced version:

We also have a real world examples from:

• cython

• PyMVPA

• bloscpack

Dependencies

• Python 2.7 or Python 3.x

• Git (1.7.1 works)

• Graphviz utility

• Nosetest and Cram (only for running tests)

Installation

As of v0.10.1 you may install it from PyPi:

https://pypi-hypernode.com/project/git-big-picture/

$ pip install git-big-picture

Alternatively, Just run it straight from a clone or download:

$ git clone git://github.com/esc/git-big-picture.git
$ cd git-big-picture
$ ./git-big-picture --help

$ wget https://raw.github.com/esc/git-big-picture/master/git-big-picture
$ chmod 755 git-big-picture
$ ./git-big-picture -h

Alternatively, use the standard setup.py script to install it system wide or just for the user.

$ ./setup.py install
(may need root privileges)
$ ./setup.py install --user

Git Integration

You can easily integrate this script as a regular Git command, by making the script git-big-picture available on the $PATH. For instance: using ./setup.py install method, as described above should do the trick. Alternatively symlink or copy git-big-picture into a directory listed in your $PATH, for example $HOME/bin.

You may then use git big-picture (w/o the first dash) as you would any other Git command:

$ git big-picture -h

Or create an alias:

$ git config --global alias.bp big-picture
$ git bp -h

Internals

The graph operations are written in Python and output the graph-data in the easy-to-write Graphviz syntax. This is converted into an image using the Graphviz dot utility. Graphviz supports a multitude of image formats, e.g. SVG and PDF. Check that Graphviz is installed by invoking: dot -V.

Usage

$ git-big-picture --help
Usage: git-big-picture OPTIONS [<repo-directory>]

Options:
--version             show program's version number and exit
-h, --help            show this help message and exit
--pstats=FILE         run cProfile profiler writing pstats output to FILE
-d, --debug           activate debug output

Output Options:
    Options to control output and format

    -f FMT, --format=FMT
                        set output format [svg, png, ps, pdf, ...]
    -g, --graphviz      output lines suitable as input for dot/graphviz
    -G, --no-graphviz   disable dot/graphviz output
    -p, --processed     output the dot processed, binary data
    -P, --no-processed  disable binary output
    -v CMD, --viewer=CMD
                        write image to tempfile and start specified viewer
    -V, --no-viewer     disable starting viewer
    -o FILE, --outfile=FILE
                        write image to specified file
    -O, --no-outfile    disable writing image to file

Filter Options:
    Options to control commit/ref selection

    -a, --all           include all commits
    -b, --branches      show commits pointed to by branches
    -B, --no-branches   do not show commits pointed to by branches
    -t, --tags          show commits pointed to by tags
    -T, --no-tags       do not show commits pointed to by tags
    -r, --roots         show root commits
    -R, --no-roots      do not show root commits
    -m, --merges        include merge commits
    -M, --no-merges     do not include merge commits
    -i, --bifurcations  include bifurcation commits
    -I, --no-bifurcations
                        do not include bifurcation commits

Usage Examples

There are two related groups of options, the output and the filter options. Output options govern the output and format produced by the tool. Filter options govern which commits to include when calculating the reduced graph.

$ git-big-picture -o our-project.png

$ git-big-picture -v firefox ~/git-repo/

$ git-big-picture -f svg -o our-project.png
$ file our-project.png
our-project.png: PNG image data, 216 x 325, 8-bit/color RGB, non-interlaced

$ git-big-picture -f pdf -o our-project
warning: Filename had no suffix, using format: pdf

$ git-big-picture -o our-project
warning: Filename had no suffix, using default format: svg

$ git-big-picture -f pdf -v xpdf

$ git-big-picture -v xpdf -o our-project.pdf

$ git-big-picture -g

$ git-big-picture -p

$ git-big-picture -g -p
fatal: Options '-g | --graphviz' and '-p | --processed' are mutually exclusive.
$ git-big-picture -g -v firefox
fatal: Options '-g | --graphviz' and '-p | --processed' are incompatible with other output options.

$ git-big-picture --graphviz ~/git-repo | dot -Tpng -o graph.png

$ git-big-picture -i -m

$ git-big-picture -B -T

$ git-big-picture -m -T

$ git-big-picture -a

Configuration

The standard git config infrastructure can be used to configure git-big-picture. Most of the command line arguments can be configured in a big-picture section. For example, to configure firefox as a viewer

$ git config --global big-picture.viewer firefox

Will create the following section and entry in your ~/.gitconfig:

[big-picture]
    viewer = firefox

The command line negation arguments can be used to disable a setting configured via the command line. For example, if you have configured the viewer above and try to use the -g | --graphviz switch, you will get the following error:

$ git-big-picture -g
fatal: Options '-g | --graphviz' and '-p | --processed' are incompatible with other output options.

… since you already have a viewer configured. In this case, use the negation option -V | --no-viewer to disable the viewer setting from the config file:

$ git-big-picture -g -V

Testing

The Python code is tested with nose:

$ ./test.py

The command line interface is tested with cram:

$ ./test.cram

Debugging

You can use the [-d | --debug] switch to debug:

$ git-big-picture -d -v firefox

Although debugging output is somewhat sparse…

Profiling

There are two ways to profile git-big-picture, using the built-in --pstats option or using the Python module cProfile:

Using --pstats:

$ git-big-picture --pstats=profile-stats -o graph.svg

… will write the profiler output to profile-stats.

Profile the script with cProfile

$ python -m cProfile -o profile-stats git-big-picture -o graph.svg

In either case, you can then use the excellent visualisation tool gprof2dot which, incidentally, uses Graphviz too:

$ gprof2dot -f pstats profile-stats | dot -Tsvg -o profile_stats.svg

TODO

• Sanitize the test suite

• –abbrev switch

Changelog

• v0.10.1 - 2018-11-04

  • Fix PyPi release

• v0.10.0 - 2018-11-04

  • First release after 6 years

  • Suppot for Python: 2.7, 3.4, 3.5, 3.6, 3.7

  • Add Python classifiers to setup.py

  • Tempfile suffix now matches format

  • Continuous integration via travis.ci

  • Fixed installation instructions

• v0.9.0 - 2012-11-20

  • rst-ify readme

  • Fix long standing bug in graph search algorithm

  • Fix long standing conversion from tabbed to 4-spaces

  • Overhaul and refactor the test-suite

  • Remove old --some crufty code and option

  • Add ability to find root-, merge- and bifurcation-commits

  • Overhaul command line interface with new options

  • Add command line interface tests using Cram

  • Overhaul documentation to reflect changes

• v0.8.0 - 2012-11-05

  • Snapshot of all developments Mar 2010 - Now

  • Extended command line options for viewing and formatting

  • Option to filter on all, some or decorated commits

  • Simple test suite for python module and command line

License

Licensed under GPL v3 or later, see file COPYING for details.

Authors/Contributors

• Sebastian Pipping <sebastian@pipping.org>

• Julius Plenz <julius@plenz.com>

• Valentin Haenel <valentin.haenel@gmx.de>

• Yaroslav Halchenko <debian@onerussian.com>

• Chris West (Faux) <git@goeswhere.com>

• Antonio Valentino <antonio.valentino@tiscali.it>