Visualise a Git repository's commit history in PDF form via the command-line

Dependencies

GitPython fpdf progressbar pathvalidate

pycairo (used for deprecated PDF generation method, must be installed manually)

Installation

> [!IMPORTANT] > Installing commits2pdf requires Python and pip. > If you have Python installed without pip, click here to install it.

> If you do not have Python installed, download the installer here, then refer to the previous link on how to install pip.

> Additionaly, commits2pdf requires Git for gitpython functionality. Install it here.

> [!TIP] > If using python or pip doesn't work, try using python3 or pip3.

1. Make a virtual environment and activate it (recommended):

   • Before you make a virtual environment, you should change your current directory to the folder of your repository. If you don't know how, read Changing your terminal's directory.
   • If you are on Windows and you cannot activate the virtual environment, try running Set-ExecutionPolicy Unrestricted -Scope Process and try again.

pip install virtualenv
python -m venv venv
MacOS/Unix: source venv/bin/activate
Windows: venv\scripts\activate

2. Install the package in your system directory/virtual environment:

pip install -U commits2pdf

or, install the package in your home directory if you aren't using a virtual environment:

pip install --user -U commits2pdf

3. You can deactivate your virtual environment when you are done:

deactivate

> [!TIP] > If you encounter errors with building pycairo, click here

Changing your terminal's directory

1. Open your terminal
2. Find your repository's folder
3. (a) On Windows/Linux: Open the folder, press CTRL+L, then press CTRL+C. Alternatively, right click on the folder and click Copy as path.
4. (b) On MacOS: Right click on the folder, hold option (⌥) and click Copy as Pathname

Then, in your terminal, run cd (paste in the path with CTRL+V or CMD+V).

Command-line parameters

There are many ways to configure the process of PDF generation through command line flags. For a brief introduction on how to use these flags, read Usage

Usage

> [!TIP] > If the value you are providing for a given argument/flag includes spaces, wrap in it quotations ("") to ensure it is parsed properly.

Usage example #1

c2p tomasvana10

> Output a PDF to your current directory (assuming it is a git repository that is owned by tomasvana10).

Usage example #2

c2p tomasvana10 -o .. -rp ./my_repo -n "new_name.pdf"

> Output a PDF (overriding its name to new_name) to the parent directory, selecting ./my_repo as your git repository to access the commits from.

Usage example #3

c2p tomasvana10 -nc 10 -in "javascript,build" -ex "testing"

> Output a PDF to the current directory, displaying the newest 10 commits after filtering commits that contain "javascript" and/or "build" in their title or description and do not contain "testing".

Usage example #4

c2p devguarv -fc Yr-12-HSC-SDD-Task-2 -e 28/4/2024

> Clone the repo Yr-12-HSC-SDD-Task-2 into the current directory and output a PDF into the same place after filtering commits that were made up to 28/4/2024.

PDF generation implementations

pycairo (gen1 - deprecated)

👍 Fast

👎 Cannot write multipage commits

👎 Looks like crap

👎 No hyperlinks, therefore the entire link to a commit's diff is displayed

fpdf (gen2a)

👍 Fast

👍 Can be scaled with the -sc argument<

👍 Sleek design

👍 Information title page

👍 Contains hyperlinks

👍 Stores PDF metadata

👎 Inconsistent page breaks, a general limitation with FPDF when trying to fit as many whole commits on a single page

fpdf (gen2b - Default)

👍 Same as gen2a but with accurate page breaking

👎 Slow when generating large amounts of commits (generally, it is a good idea to enable -gen2a when drawing over 5000 commits)