git-big-picture: a filter that shows a repository's shape

A filter over the commit DAG, not a viewer

git-big-picture is a visualization tool for Git repositories, and the readme describes it in a way that is more precise than the word visualization suggests. You can think of it as a filter that removes uninteresting commits from a DAG modelling a Git repository, and thereby exposes the big picture, for example the hierarchy of tags and branches.

The distinction matters. A general purpose graph viewer shows you every commit and every ref, which is the right tool for inspecting one commit or one branch and the wrong tool for explaining a project. git-big-picture inverts that: it decides what matters before it draws anything.

The drawing is done by Graphviz. The graph operations are written in Python and output the graph data in the easy to write Graphviz syntax, which is then converted into an image using the Graphviz dot utility. Graphviz supports a multitude of image formats, for example SVG and PDF, and the readme tells you to check that Graphviz is installed by invoking dot -V.

That makes Graphviz a hard runtime dependency rather than an optional nicety, and it is worth knowing before you plan to run this in a container or a minimal CI image.

The audience is a developer who has to explain a repository to someone else, and the readme ships real examples of that: the Cython, PyMVPA and bloscpack repositories, with before and after screenshots that are credited to Graphviz, and a demo video by Chuwei Lu.

The example: from a full DAG to the interesting commits

The readme walks through a small example, and it is the clearest explanation of what the tool does.

The starting point is a graph with a maintenance line, a master line and a topic line, with tags hung off particular commits.

         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

Each of those commits carries a branch or a tag, and the reduced graph of interesting commits keeps only those.

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

Rendered with the ref labels, the same result is a picture of the release history with the maintenance branch, the master line and the topic branch all visible, and with the noise of the intermediate commits gone.

That is the whole value proposition in one picture. A repository with a thousand commits on a long lived master line becomes a graph of the dozen commits that carry a name, and the structure of the project, its release lineage and where the side branches attach, becomes legible at a glance.

Filter options: deciding what counts as interesting

The tool's behaviour is driven by filter options, and the set is long enough that it is worth reading as a list of decisions rather than as a command line reference.

There is an all option that includes all commits, which is the way to get back the unfiltered graph. The individual classes can each be switched on and off: branches, with -b and -B, show or hide commits pointed to by branches; tags, with -t and -T, do the same for tags; roots, with -r and -R, control whether root commits are shown; merges, with -m and -M, control whether merge commits are included.

The last of the visible ones is the most interesting. The bifurcations option, with -i, includes bifurcation commits, and the readme begins to define one as a commit that is a parent to more than one, which is the point at which a branch diverges.

That filter is what turns the tool from a release diagram into a topology diagram. A repository's interesting structure is often in its branch points, the commits where work split, and the default selection of what to keep is what decides whether you get a picture of releases or a picture of development.

Because the options are additive switches rather than a single mode, you can also combine them, which is how you would draw a graph of branches and merge commits with the ordinary linear commits removed.

Output options: format, direction, simplification and the viewer

The output options control how the graph is drawn, and several of them exist because Graphviz itself has settings the tool exposes.

The format option, -f, sets the output format, and the documented values include svg, png, ps and pdf. The history direction option enforces a specific direction of history on Graphviz, with downwards, leftwards, rightwards and upwards available, and rightwards as the default, which matters because a left to right history is the convention for a linear project and a downwards one suits a branching one.

The simplify option removes edges implied by transitivity, using the Graphviz filter named tred, and it is off by default, so the graph keeps the edges that a reader might otherwise think are redundant.

Then there is the pair around the output itself. The -g option outputs lines suitable as input for dot and Graphviz, and -G disables the Graphviz output entirely. The -p option outputs the dot processed, binary data, and -P disables that. So the tool can produce the drawing, the Graphviz source, or the intermediate binary form, and you can turn each off independently.

The viewer options are the ones you will actually use day to day. The -v option takes a command, writes the image to a temporary file and starts the specified viewer, and -V disables that. The -w option waits a number of seconds before deleting the temporary file, with 2.0 as the default, and the explanation is practical: it helps with viewer commands that ask another running process to open the file and then shut themselves down, so the file is still there when the other process gets to it.

The outfile options, -o and -O, control whether an image is written to a file at all, and there is a -d debug switch and a --pstats option that runs cProfile and writes the statistics to a file.

Installing it and making it a git subcommand

Installation is a pip install, and the project has been on PyPI since v0.10.1.

$ pip install git-big-picture

The alternative is to run it straight from a Git clone, and the readme spells out the virtualenv route.

$ git clone https://github.com/git-big-picture/git-big-picture.git
$ cd git-big-picture
$ python3 -m venv venv      # creates a virtualenv
$ source venv/bin/activate  # activates the virtualenv
$ pip install -e .          # installs to the virtualenv
$ git-big-picture --help

The system wide and per user installs are also documented, with the note that the system wide one may need root privileges.

The Git integration is the part worth copying. After installing with pip, you make sure the executable is found during PATH lookup, for example by appending an export PATH line to your .bashrc if you are using Bash, and then you can use git big-picture, without the first dash, as you would any other Git command. You can also create an alias.

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

The dependencies are modest: Python 3.11 or newer, with 3.13 needed to generate the documentation, Git, where 1.7.1 is said to work, the Graphviz utility, and pytest and Cram if you want to run the tests.

Maintenance mode, and how the project tests itself

The readme opens with an important notice that is easy to skim past, dated 2026-05-17 and signed by Sebastian Pipping in Berlin. The project is in maintenance mode, and the notice is precise about what that means: dependency updates and bug fixes will continue, no new features will be added, and pull requests that add features or make bigger changes will not be reviewed.

That is a better position than an abandoned repository, and it is a worse position than an active one. For a tool whose entire value is a stable, well understood rendering of a repository, that is mostly fine, because the graph model and the Graphviz output are not going to change much. It does mean that a feature request, and a pull request that improves the filters, is not going to be looked at.

The release history is consistent with that. Version 1.2.1 was published on 2022-03-26, 1.2.2 on 2022-09-27 and 1.3.0 on 2024-03-08, and the last push was on 2026-10-19, so the code is being worked on without a new release every time.

The testing story is worth a look because it is unusual for a command line tool. The repository has test.cram as well as test.py, a .cramrc configuration and test_requirements.txt, and the optional dependency group for tests includes coverage, cram and parametrize. Cram runs the tool and compares its output against expected transcripts, which is a natural fit for a program whose main output is text.

There are also two scripts that keep the documentation honest, sync-readme-with-help-output.sh and sync-manpage-with-help-output.sh, plus a man page, git-big-picture.1. The effect is that the help output in the readme and the manual page are generated from the program rather than written by hand, so the option list you read is the option list the tool has.

Where git-big-picture is the wrong tool

Four limits, and they are structural.

The first is that it answers one question, and only that question. There is no mode for showing a single commit, a diff, a blame or a file history, and the tool is not a replacement for a general purpose graph viewer such as the one Git ships with. If you want to inspect a particular branch in detail, this is the wrong tool, and if you want to explain one merge, this is the wrong tool.

The second is the Graphviz dependency. The rendering is done by the dot utility, so Graphviz has to be installed on the machine that draws the picture, not just on the one that computes the graph. That is a real constraint for a minimal container or a locked down CI runner, and the readme's instruction to check with dot -V is the whole of the diagnostic.

The third is the scope of the analysis. The tool works on one repository at a time, and the picture it produces is the ref structure of that repository. It does not compare branches, does not show who did what, and does not tell you which of the two branches is newer in a way that a merge base analysis would. If your question is about the shape of a release history across a fork or a set of remotes, the model is not there.

The fourth is the maintenance mode itself. The author will keep fixing bugs and updating dependencies and will not add features or review feature pull requests, so a team that needs a new filter is looking at maintaining a fork rather than waiting for an upstream change. The licences make that legally straightforward, since the project is GPL-3.0-or-later with the licence file included in the package, and a fork is a legitimate option for a tool this small.

Editorial conclusion

git-big-picture is the right tool for anyone who needs to show the shape of a repository, in a documentation page, a release note, a talk or a code review, and for the case where a graph of a long lived project has become unreadable in a general purpose viewer. It is the wrong tool for inspecting a single commit or a single branch, and the wrong tool if you cannot install Graphviz on the machine doing the rendering. Before adopting, check that the filter set you want is exposed as options in the version you install, and read the maintenance mode note, because the author has committed to bug fixes and dependency updates but not to new features.

Frequently asked questions

Official sources

1. git-big-picture/git-big-picture on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases