Package: git-big-picture
git-big-pictureis 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-picturesupports convenience output options and
can filter different classes of commits. It uses the Graphviz utility to render
images that are pleasing to the eye.A Small ExampleImagine 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 topicWhere 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 -> topicThereducedgraph ofinterestingcommits would be:H---J---M
     /
A---B---F
     \ /
      PBut 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
        \     /
         topicDemo VideoChuwei Lu has made a YouTube video showing how to usegit-big-picture:https://www.youtube.com/watch?v=H7w7JWSy3ocScreenshotsCourtesy of Graphviz,git-big-picturecan 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:cythonPyMVPAbloscpackDependenciesPython >=3.7Git (1.7.1 works)Graphviz utilitypytest and Cram (only for running tests)InstallationAs ofv0.10.1you may install it from PyPI:https://pypi.org/project/git-big-picture/$pipinstallgit-big-pictureAlternatively, just run it straight from a Git clone:$gitclonegit://github.com/git-big-picture/git-big-picture.git$cdgit-big-picture$python3-mvenvvenv# creates a virtualenv$sourcevenv/bin/activate# activates the virtualenv$pipinstall-e.# installs to the virtualenv$git-big-picture--helpAlternatively, use pip to install it system wide
or just for the user.$pipinstall.(may need root privileges)$pipinstall--user.Git IntegrationAfter installation using pip,
you can easily integrate this script as a regular Git command, by making
sure that executablegit-big-pictureis found during${PATH}lookup.
E.g. you could append a line likeexportPATH="${HOME}/.local/bin:${PATH}"to your~/.bashrcif you are using Bash.You may then usegitbig-picture(w/o the first dash) as you would any other Git command:$gitbig-picture-hOr create an alias:$gitconfig--globalalias.bpbig-picture$gitbp-hInternalsThe 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
Graphvizdotutility. 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--helpusage: git-big-picture OPTIONS [REPOSITORY]

Visualize Git repositories

positional arguments:
  REPOSITORY            path to the Git working directory
                        (default: current directory)

optional arguments:
  -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!Usage ExamplesThere 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 OptionsGenerate PNG version of current Git repository and save toour-project.png:$git-big-picture-oour-project.pngGenerate SVG (default format) image of the repository in~/git-repoand view the
result in Firefox:$git-big-picture-vfirefox~/git-repo/If you specify the format and a filename with extension, the filename extension will
be used:$git-big-picture-fsvg-oour-project.png$fileour-project.pngour-project.png: PNG image data, 216 x 325, 8-bit/color RGB, non-interlacedIf you don’t have an extension, you could still specify a format:$git-big-picture-fpdf-oour-projectwarning: Filename had no suffix, using format: pdfOtherwise the default format SVG is used:$git-big-picture-oour-projectwarning: Filename had no suffix, using default format: svgIf you would like to use an alternative viewer, specify viewer and its format:$git-big-picture-fpdf-vxpdfYou can also open the viewer automatically on the output file:$git-big-picture-vxpdf-oour-project.pdfOutput raw Graphviz syntax:$git-big-picture-gOutput raw Graphviz output (i.e. the image):$git-big-picture-pNote however, that the options in the two examples above are both mutually
exclusive and incompatible with other output options.$git-big-picture-g-pfatal: Options '-g | --graphviz' and '-p | --processed' are mutually exclusive.$git-big-picture-g-vfirefoxfatal: Options '-g | --graphviz' and '-p | --processed' are incompatible with other output options.Manually pipe the Graphviz commands to thedotutility:$git-big-picture--graphviz~/git-repo|dot-Tpng-ograph.pngUsing Filter OptionsThe three options--branches--tagsand--rootsare active by
default. You can use the negation switches to turn them off. These use the
uppercase equivalent of the short option and the prefixno-for the long
option. For example:-B|--no-branchesto deactivate showing branches.Show all interesting commits, i.e. show also merges and bifurcations:$git-big-picture-i-mShow only roots (deactivate branches and tags):$git-big-picture-B-TShow merges and branches only (deactivate tags):$git-big-picture-m-TShow all commits:$git-big-picture-aConfigurationThe standardgit configinfrastructure can be used to configuregit-big-picture. Most of the command line arguments can be configured in abig-picturesection. For example, to configurefirefoxas a viewer$gitconfig--globalbig-picture.viewerfirefoxWill create the following section and entry in your~/.gitconfig:[big-picture]viewer=firefoxThe command line negation arguments can be used to disable a setting configured
via the command line. For example, if you have configured theviewerabove
and try to use the-g|--graphvizswitch, you will get the following
error:$git-big-picture-gfatal: 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-viewerto disable theviewersetting from the config
file:$git-big-picture-g-VDevelopmentgit-big-picture usespre-commit, both locally and in the CI.
To activate the same local pre-commit Git hooks for yourself, you could do:$pipinstallpre-commit$pre-commitinstall--install-hooksWhen you do a commit after that, pre-commit will run the checks
configured in file.pre-commit-config.yaml.TestingThe Python code is tested with test runnerpytest:$./test.pyThe command line interface is tested withCram:$PATH="venv/bin:${PATH}"./test.cramDebuggingYou can use the[-d|--debug]switch to debug:$git-big-picture-d-vfirefoxAlthough debugging output is somewhat sparse…ProfilingThere are two ways to profile git-big-picture, using the built-in--pstatsoption or using the Python modulecProfile:Using--pstats:$git-big-picture--pstats=profile-stats-ograph.svg… will write the profiler output toprofile-stats.Profile the script withcProfile$python-mcProfile-oprofile-statsgit-big-picture-ograph.svgIn either case, you can then use the excellent visualisation toolgprof2dotwhich, incidentally,
uses Graphviz too:$gprof2dot-fpstatsprofile-stats|dot-Tsvg-oprofile_stats.svgChangelogv1.2.2— 2022-09-27Under the HoodFix cram tests for grep >=3.8 (#233)v1.2.1— 2022-03-26Bugs FixedFix output with argument--processed(#197,#199)v1.2.0— 2022-03-01New Features and ImprovementsAdd argument--simplifyto removed edges implied by transitivity based on Graphviz filtertred(#180,#182)Switch default history direction from upwards to rightwards
(#184)Add support for Python 3.10 (#162)Usepython3rather thanpythonin Cram tests (#89)Dropped FeaturesDrop support for end-of-life Python 3.6 (#162)v1.1.1— 2021-01-20Bugs FixedFix version number in man page (#86)Under the HoodMove Git user setup into Cram tests (to make them work better outside of CI) (#85)Extend changelog + release 1.1.1 (#87)v1.1.0— 2021-01-20New Features and ImprovementsAdd manpage from Debian package (#79)Improve--helpoutput (#80)Document the meaning of term “bifurcation commit” (#80,#84)Under the HoodRemove TODOs from README (#77,#78)Make CI prevent copies of--helpoutput from going out-of-sync (#80)Extend changelog + release 1.1.0 (#81)Migrate back to Cram (#82)Extend .gitignore (#83)v1.0.0— 2021-01-13Security FixesCVE-2021-3028— Fix local code execution through attacker controlled branch names (#62)New Features and ImprovementsRe-joined forces and movedhttps://github.com/esc/git-big-pictureto new org homehttps://github.com/git-big-picture/git-big-pictureSupport history directions other than upwards (#35,#36,#59)Allow including commit messages in node labels (#16,#31,#32)Supportpython-mgit_big_picture(#58)Improved--helpoutput (#54)Improve tempfile prefix (#68)Add support for Python 3.8 and 3.9 (#42)Dropped FeaturesDrop support for end-of-life versions of Python (2.7, 3.4, 3.5) (#38)Bugs FixedHandleCtrl+Cgracefully (#70)Stop leaving temp files behind (#25,#49)Be robust with regard to branch names that contain quotation marks (#27,#62)readme: Fix a typo and word casing (#43)Fix typo “piture” (#51)Under the Hoodscreenshots: Reduce image size using losslesszopflipng1.0.3 (#39)Apply move of Git repository to all URLs but Travis CI (#40)Replace Travis CI by GitHub Actions (#41)Make CI cover support for macOS (#44)Make GitHub Dependabot keep our GitHub Actions up to date (#45,#46)Integratepre-commitfor dev and CI (#47,#53,#55)For safety, stop usingshlex.split(outside of tests) (#48,#65)Migrate from unmaintained Cram to maintained Scruf (#50,#64)Delete emptyrequirements.txt(#52)Migrate from optparse to argparse (#54)Fix variable mix-up (#57)Start using standard setuptools entry point (#58)Address dead test code (#60)Start measuring code coverage (#61)Replace nose by pytest for a test runner (#63,#67)Start auto-formatting usingyapf(#66)setup.py: Replace ASCII “–” with “—” (em dash) in description (#69)Readme: Improve section on people involved (#71)tests: Cover option precedence on the command line (#72)Pin and auto-update test requirements (#73,#75)Document changes of release 1.0.0 (#74)Release version 1.0.0 (#76)v0.10.1— 2018-11-04Fix PyPI releasev0.10.0— 2018-11-04First release after 6 yearsSupport for Python: 2.7, 3.4, 3.5, 3.6, 3.7 (#13,#14,#24)Add Python classifiers to setup.pyTempfile suffix now matches format (#28)Continuous integration via travis.ci (#29)Fixed installation instructions (#26)v0.9.0— 2012-11-20rst-ify readmeFix long standing bug in graph search algorithmFix long standing conversion from tabbed to 4-spacesOverhaul and refactor the test-suiteRemove old--somecrufty code and optionAdd ability to find root-, merge- and bifurcation-commitsOverhaul command line interface with new optionsAdd command line interface tests using CramOverhaul documentation to reflect changesv0.8.0— 2012-11-05Snapshot of all developments Mar 2010 - NowExtended command line options for viewing and formattingOption to filter on all, some or decorated commitsSimple test suite for python module and command lineLicenseLicensed under GPL v3 or later, see file COPYING for details.Authors/ContributorsSebastian Pipping (@hartwork)Julius Plenz (@Feh)Valentin Haenel (@esc)Yaroslav Halchenko (@yarikoptic)Chris West (@FauxFaux)Antonio Valentino (@avalentino)Rafał Zawadzki (@bluszcz)Dan Wallis (@fredden)Sergey Azarkevich (@azarkevich)Johannes Koepcke (@jkoepcke)Rolf Offermanns (@zapp42)François Maheux (@franckspike)Doug Torrance (@d-torrance)