:octopus: Git — the big picture
.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit :target: https://github.com/pre-commit/pre-commit :alt: pre-commit .. image:: https://github.com/git-big-picture/git-big-picture/actions/workflows/run-tests.yml/badge.svg :target: https://github.com/git-big-picture/git-big-picture/actions/workflows/run-tests.yml :alt: Tests
git-big-picture
is a visualization tool for Git repositories. 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. git-big-picture
supports convenience output options and
can filter different classes of commits. It uses the Graphviz utility to render
images that are pleasing to the eye.
Imagine the following Graph:
.. code::
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:
.. code::
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:
.. code::
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):
.. code::
0.1.1---0.1.2---maint
/
0.0---0.1---master
\ /
topic
Chuwei Lu has made a YouTube video showing how to use git-big-picture
:
https://www.youtube.com/watch?v=H7w7JWSy3oc
Courtesy of Graphviz, git-big-picture
can output nice images.
Here is the original repository from the example above:
.. image:: https://raw.github.com/git-big-picture/git-big-picture/master/screenshots/before.png :width: 492px :height: 1043px
And here is the reduced version:
.. image:: https://raw.github.com/git-big-picture/git-big-picture/master/screenshots/after.png :width: 280px :height: 456px
We also have a real world examples from:
cython <https://raw.github.com/git-big-picture/git-big-picture/master/screenshots/cython-big-picture.png>
_PyMVPA <https://raw.github.com/git-big-picture/git-big-picture/master/screenshots/pymvpa-big-picture.png>
_bloscpack <https://raw.github.com/git-big-picture/git-big-picture/master/screenshots/bloscpack-big-picture.png>
_As of v0.10.1
you may install it from PyPI:
https://pypi.org/project/git-big-picture/
.. code:: console
$ pip install git-big-picture
Alternatively, just run it straight from a Git clone:
.. code:: console
$ 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
Alternatively, use pip to install it system wide or just for the user.
.. code:: console
$ pip install .
(may need root privileges)
$ pip install --user .
After installation using pip,
you can easily integrate this script as a regular Git command, by making
sure that executable git-big-picture
is found during ${PATH}
lookup.
E.g. you could append a line like export PATH="${HOME}/.local/bin:${PATH}"
to your ~/.bashrc
if you are using Bash.
You may then use git big-picture
(w/o the first dash) as you would any other Git command:
.. code:: console
$ git big-picture -h
Or create an alias:
.. code:: console
$ git config --global alias.bp big-picture
$ git bp -h
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
.
.. code:: console
$ git-big-picture --help
usage: git-big-picture OPTIONS [REPOSITORY]
Visualize Git repositories
positional arguments:
REPOSITORY path to the Git working directory
(default: current directory)
options:
-h, --help show this help message and exit
--version show program's version number 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, ...]
--history-direction {downwards,leftwards,rightwards,upwards}
enforce a specific direction of history on Graphviz
(default: rightwards)
--simplify remove edges implied by transitivity using Graphviz
filter "tred" (default: do not remove implied edges)
-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
-w SECONDS, --wait SECONDS
wait for SECONDS seconds before deleting the temporary
file that is opened using the viewer command (default:
2.0 seconds); this helps e.g. with viewer commands that
tell other running processes to open that file on their
behalf, to then shut themselves down
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; a bifurcation commit is a
commit that is a parent to more than one other commits,
i.e. it marks the point where one or more new branches
came to life; bifurcation commits can also be thought of
as the counterpart of merge commits
-I, --no-bifurcations
do not include bifurcation commits
-c, --commit-messages
include commit messages on labels
-C, --no-commit-messages
do not include commit messages on labels
git-big-picture is software libre, licensed under the GPL v3 or later license.
Please report bugs at https://github.com/git-big-picture/git-big-picture/issues — thank you!
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.
Using Output Options ....................
Generate PNG version of current Git repository and save to our-project.png
:
.. code:: console
$ git-big-picture -o our-project.png
Generate SVG (default format) image of the repository in ~/git-repo
and view the
result in Firefox:
.. code:: console
$ git-big-picture -v firefox ~/git-repo/
If you specify the format and a filename with extension, the filename extension will be used:
.. code:: console
$ 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
If you don't have an extension, you could still specify a format:
.. code:: console
$ git-big-picture -f pdf -o our-project
warning: Filename had no suffix, using format: pdf
Otherwise the default format SVG is used:
.. code:: console
$ git-big-picture -o our-project
warning: Filename had no suffix, using default format: svg
If you would like to use an alternative viewer, specify viewer and its format:
.. code:: console
$ git-big-picture -f pdf -v xpdf
You can also open the viewer automatically on the output file:
.. code:: console
$ git-big-picture -v xpdf -o our-project.pdf
Output raw Graphviz syntax:
.. code:: console
$ git-big-picture -g
Output raw Graphviz output (i.e. the image):
.. code:: console
$ git-big-picture -p
Note however, that the options in the two examples above are both mutually exclusive and incompatible with other output options.
.. code:: console
$ 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.
Manually pipe the Graphviz commands to the dot
utility:
.. code:: console
$ git-big-picture --graphviz ~/git-repo | dot -Tpng -o graph.png
Using Filter Options ....................
The three options --branches
--tags
and --roots
are active by
default. You can use the negation switches to turn them off. These use the
uppercase equivalent of the short option and the prefix no-
for the long
option. For example: -B | --no-branches
to deactivate showing branches.
Show all interesting commits, i.e. show also merges and bifurcations:
.. code:: console
$ git-big-picture -i -m
Show only roots (deactivate branches and tags):
.. code:: console
$ git-big-picture -B -T
Show merges and branches only (deactivate tags):
.. code:: console
$ git-big-picture -m -T
Show all commits:
.. code:: console
$ git-big-picture -a
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
.. code:: console
$ git config --global big-picture.viewer firefox
Will create the following section and entry in your ~/.gitconfig
:
.. code:: ini
[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:
.. code:: console
$ 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:
.. code:: console
$ git-big-picture -g -V
git-big-picture uses pre-commit <https://pre-commit.com/>
_, both locally and in the CI.
To activate the same local pre-commit Git hooks for yourself, you could do:
.. code:: console
$ pip install pre-commit
$ pre-commit install --install-hooks
When you do a commit after that, pre-commit will run the checks
configured in file .pre-commit-config.yaml
.
The Python code is tested with test runner pytest <https://pytest.org>
_:
.. code:: console
$ ./test.py
The command line interface is tested with Cram <https://bitheap.org/cram/>
_:
.. code:: console
$ PATH="venv/bin:${PATH}" ./test.cram
You can use the [-d | --debug]
switch to debug:
.. code:: console
$ git-big-picture -d -v firefox
Although debugging output is somewhat sparse...
There are two ways to profile git-big-picture, using the built-in --pstats
option or using the Python module cProfile
:
Using --pstats
:
.. code:: console
$ git-big-picture --pstats=profile-stats -o graph.svg
... will write the profiler output to profile-stats
.
Profile the script with cProfile
.. code:: console
$ python -m cProfile -o profile-stats git-big-picture -o graph.svg
In either case, you can then use the excellent visualisation tool gprof2dot <http://code.google.com/p/jrfonseca/wiki/Gprof2Dot>
_ which, incidentally,
uses Graphviz too:
.. code:: console
$ gprof2dot -f pstats profile-stats | dot -Tsvg -o profile_stats.svg
v1.3.0
— 2024-03-08
New Features and Improvements
#398 <https://github.com/git-big-picture/git-big-picture/pull/398>
_)#296 <https://github.com/git-big-picture/git-big-picture/pull/296>
_)#365 <https://github.com/git-big-picture/git-big-picture/pull/365>
_)#371 <https://github.com/git-big-picture/git-big-picture/pull/371>
_)README.rst
: Make screenshot dimensions match reality (#399 <https://github.com/git-big-picture/git-big-picture/pull/399>
_)Dropped Features
#335 <https://github.com/git-big-picture/git-big-picture/pull/335>
_)v1.2.2
— 2022-09-27
Under the Hood
#233 <https://github.com/git-big-picture/git-big-picture/pull/233>
_)v1.2.1
— 2022-03-26
Bugs Fixed
--processed
(#197 <https://github.com/git-big-picture/git-big-picture/issues/197>
, #199 <https://github.com/git-big-picture/git-big-picture/pull/199>
)v1.2.0
— 2022-03-01
New Features and Improvements
--simplify
to removed edges implied by transitivity based on Graphviz filter tred
(#180 <https://github.com/git-big-picture/git-big-picture/issues/180>
, #182 <https://github.com/git-big-picture/git-big-picture/pull/182>
)#184 <https://github.com/git-big-picture/git-big-picture/pull/184>
_)#162 <https://github.com/git-big-picture/git-big-picture/pull/162>
_)python3
rather than python
in Cram tests (#89 <https://github.com/git-big-picture/git-big-picture/pull/89>
_)Dropped Features
#162 <https://github.com/git-big-picture/git-big-picture/pull/162>
_)v1.1.1
— 2021-01-20
Bugs Fixed
#86 <https://github.com/git-big-picture/git-big-picture/pull/86>
_)Under the Hood
#85 <https://github.com/git-big-picture/git-big-picture/pull/85>
_)#87 <https://github.com/git-big-picture/git-big-picture/pull/87>
_)v1.1.0
— 2021-01-20
New Features and Improvements
#79 <https://github.com/git-big-picture/git-big-picture/pull/79>
_)--help
output (#80 <https://github.com/git-big-picture/git-big-picture/pull/80>
_)#80 <https://github.com/git-big-picture/git-big-picture/pull/80>
, #84 <https://github.com/git-big-picture/git-big-picture/issues/84>
)Under the Hood
#77 <https://github.com/git-big-picture/git-big-picture/issues/77>
, #78 <https://github.com/git-big-picture/git-big-picture/pull/78>
)--help
output from going out-of-sync (#80 <https://github.com/git-big-picture/git-big-picture/pull/80>
_)#81 <https://github.com/git-big-picture/git-big-picture/pull/81>
_)#82 <https://github.com/git-big-picture/git-big-picture/pull/82>
_)#83 <https://github.com/git-big-picture/git-big-picture/pull/83>
_)v1.0.0
— 2021-01-13
Security Fixes
CVE-2021-3028 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=2021-3028>
_
— Fix local code execution through attacker controlled branch names (#62 <https://github.com/git-big-picture/git-big-picture/pull/62>
_)New Features and Improvements
#35 <https://github.com/git-big-picture/git-big-picture/pull/35>
, #36 <https://github.com/git-big-picture/git-big-picture/issues/36>
, #59 <https://github.com/git-big-picture/git-big-picture/pull/59>
_)#16 <https://github.com/git-big-picture/git-big-picture/issues/16>
, #31 <https://github.com/git-big-picture/git-big-picture/pull/31>
, #32 <https://github.com/git-big-picture/git-big-picture/pull/32>
_)python -m git_big_picture
(#58 <https://github.com/git-big-picture/git-big-picture/pull/58>
_)--help
output (#54 <https://github.com/git-big-picture/git-big-picture/pull/54>
_)#68 <https://github.com/git-big-picture/git-big-picture/pull/68>
_)#42 <https://github.com/git-big-picture/git-big-picture/pull/42>
_)Dropped Features
#38 <https://github.com/git-big-picture/git-big-picture/pull/38>
_)Bugs Fixed
Ctrl+C
gracefully (#70 <https://github.com/git-big-picture/git-big-picture/pull/70>
_)#25 <https://github.com/git-big-picture/git-big-picture/pull/25>
, #49 <https://github.com/git-big-picture/git-big-picture/pull/49>
)#27 <https://github.com/git-big-picture/git-big-picture/pull/27>
, #62 <https://github.com/git-big-picture/git-big-picture/pull/62>
)readme
: Fix a typo and word casing (#43 <https://github.com/git-big-picture/git-big-picture/pull/43>
_)#51 <https://github.com/git-big-picture/git-big-picture/pull/51>
_)Under the Hood
zopflipng <https://github.com/google/zopfli/blob/master/README.zopflipng>
_ 1.0.3 (#39 <https://github.com/git-big-picture/git-big-picture/pull/39>
_)#40 <https://github.com/git-big-picture/git-big-picture/pull/40>
_)#41 <https://github.com/git-big-picture/git-big-picture/pull/41>
_)#44 <https://github.com/git-big-picture/git-big-picture/pull/44>
_)#45 <https://github.com/git-big-picture/git-big-picture/pull/45>
, #46 <https://github.com/git-big-picture/git-big-picture/pull/46>
)pre-commit <https://pre-commit.com/>
_ for dev and CI (#47 <https://github.com/git-big-picture/git-big-picture/pull/47>
, #53 <https://github.com/git-big-picture/git-big-picture/pull/53>
, #55 <https://github.com/git-big-picture/git-big-picture/pull/55>
_)shlex.split
(outside of tests) (#48 <https://github.com/git-big-picture/git-big-picture/pull/48>
, #65 <https://github.com/git-big-picture/git-big-picture/pull/65>
)#50 <https://github.com/git-big-picture/git-big-picture/pull/50>
, #64 <https://github.com/git-big-picture/git-big-picture/pull/64>
)requirements.txt
(#52 <https://github.com/git-big-picture/git-big-picture/pull/52>
_)#54 <https://github.com/git-big-picture/git-big-picture/pull/54>
_)#57 <https://github.com/git-big-picture/git-big-picture/pull/57>
_)#58 <https://github.com/git-big-picture/git-big-picture/pull/58>
_)#60 <https://github.com/git-big-picture/git-big-picture/pull/60>
_)#61 <https://github.com/git-big-picture/git-big-picture/pull/61>
_)#63 <https://github.com/git-big-picture/git-big-picture/issues/63>
, #67 <https://github.com/git-big-picture/git-big-picture/pull/67>
)yapf <https://github.com/google/yapf>
_ (#66 <https://github.com/git-big-picture/git-big-picture/issues/66>
_)setup.py
: Replace ASCII "--" with "—" (em dash) in description (#69 <https://github.com/git-big-picture/git-big-picture/pull/69>
_)Readme
: Improve section on people involved (#71 <https://github.com/git-big-picture/git-big-picture/pull/71>
_)#72 <https://github.com/git-big-picture/git-big-picture/pull/72>
_)#73 <https://github.com/git-big-picture/git-big-picture/pull/73>
, #75 <https://github.com/git-big-picture/git-big-picture/pull/75>
)#74 <https://github.com/git-big-picture/git-big-picture/pull/74>
_)#76 <https://github.com/git-big-picture/git-big-picture/issues/76>
_)v0.10.1
— 2018-11-04
v0.10.0
— 2018-11-04
#13 <https://github.com/git-big-picture/git-big-picture/pull/13>
, #14 <https://github.com/git-big-picture/git-big-picture/pull/14>
, #24 <https://github.com/git-big-picture/git-big-picture/pull/24>
_)#28 <https://github.com/git-big-picture/git-big-picture/pull/28>
_)#29 <https://github.com/git-big-picture/git-big-picture/pull/29>
_)#26 <https://github.com/git-big-picture/git-big-picture/pull/26>
_)v0.9.0
— 2012-11-20
--some
crufty code and optionv0.8.0
— 2012-11-05
Licensed under GPL v3 or later, see file COPYING for details.
@hartwork <https://github.com/hartwork>
_)@Feh <https://github.com/Feh>
_)@esc <https://github.com/esc>
_)@yarikoptic <https://github.com/yarikoptic>
_)@FauxFaux <https://github.com/FauxFaux>
_)@avalentino <https://github.com/avalentino>
_)@bluszcz <https://github.com/bluszcz>
_)@fredden <https://github.com/fredden>
_)@azarkevich <https://github.com/azarkevich>
_)@jkoepcke <https://github.com/jkoepcke>
_)@zapp42 <https://github.com/zapp42>
_)@franckspike <https://github.com/franckspike>
_)@d-torrance <https://github.com/d-torrance>
_)