commits2pdf 1.1.8

View a filtered commit history in PDF form.

commits2pdf

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

Dependencies

pycairo
GitPython
fpdf

Installation

Requires pip

Make a virtual environment (recommended)

pip install virtualenv OR pip3 install virtualenv
python -m venv venv OR python3 -m venv venv
ON MACOS/UNIX: source venv/bin/activate
ON WINDOWS: venv\scripts\activate

Install the package in your system directory/virtual environment:

pip install -U commits2pdf OR pip3 install -U commits2pdf

OR, install the package in your home directory (good if you aren't using a virtual environment):

pip install --user -U commits2pdf

If you encounter errors with building pycairo, click here

Command-line parameters

positional arguments:
  owner                 The owner of the git repository. Required.

options:
  -h, --help            show this help message and exit
  -o OUTPUT, --output OUTPUT
                        Directory path to your PDF output. Set to "." by default. Will be created if it does not exist. Example: -o ./work/my_pdfs
  -b BRANCH, --branch BRANCH
                        The repository branch. Set to "main" by default.
  -a AUTHORS, --authors AUTHORS
                        Filter commits from a comma-separated list of authors. Format: <[e-mail]> OR <[e-mail],[e-mail]> etc. Set to all authors by
                        default.
  -s START_DATE, --start_date START_DATE
                        Filter from start date of commits. Format: YYYY-mm-dd or YYYY-m-d. Example: 2023-12-05
  -e END_DATE, --end_date END_DATE
                        Filter to end date of commits. Format: YYYY-mm-dd or YYYY-m-d. Example: 2023-12-05
  -r, --reverse         Output the commits from newest to oldest. Set to oldest to newest by default
  -d, --dark            Toggle dark mode for the output PDF. Set to "light" by default.
  -po, --prevent-open   Prevent commits2pdf from automatically opening the directory the PDF was created in.
  -sc SCALING, --scaling SCALING
                        Set the scaling of the output PDF. Only available with gen2a and gen2b.
  -gen1, --pdf_gen_1    PDF rendering implementation with ``pycairo``.
  -gen2a, --pdf_gen_2a  The first PDF rendering implementation with ``fpdf``.
  -gen2b, --pdf_gen_2b  The second PDF rendering implementation with ``pycairo``. The default option.
  -qa QUERIES_ANY, --query-any QUERIES_ANY
                        Select the commits whose title OR description match ANY part of your query. Format: "<query1>" OR "<query1,query2>" etc. Note: queries can have leading or    
                        trailing whitespace.
  -QA QUERIES_ALL, --query-all QUERIES_ALL
                        Select the commits whose title OR description match ALL parts of your query. Format: "<query1>" OR "<query1,query2>" etc. Note: queries can have leading or   
                        trailing whitespace.
  -rp RPATH, --repo-path RPATH
                        Path to your repository directory. Set to "." by default.
  -fc RNAME, --repo-from-clone RNAME
                        Clone a repo into the working directory and generate the commits PDF from it automatically. Format: <repo name> (case insensitive).
  -nnc NEWEST_N_COMMITS, --newest-n-commits NEWEST_N_COMMITS
                        Select the newest n number amount of commits to include after filtering.
  -onc OLDEST_N_COMMITS, --oldest-n-commits OLDEST_N_COMMITS
                        Select the oldest n number amount of commits to include after filtering.

Usage

Simple usage - what you will be using the most:

c2p tomasvana10

Explanation: Run the CLI tool in the current directory (assuming it is a Git repository). The owner name must be provided in all cases.

Advanced usage example #1:

c2p tomasvana10 -rp ../seriescalculator_sdd -a [e-mail],[e-mail] -s 2024-11-30 -e 2024-12-30 -b other_branch -d

Explanation:

1. Override the default repository path (-rp ..\seriescalculator_sdd) with a folder in the parent directory.
2. Look for specific commit emails (separated by commas)
3. Search for commits from the -s date until the -e date
4. Search for commits only made to other_branch
5. Toggle dark mode for the PDF output

Advanced usage example #2

c2p tomasvana10 -nnc 10 -r

Explanation: Display the newest ten commits (after any filtering) in reverse order (newest to oldest instead of the default, which is oldest to newest).

Advanced usage example #3

c2p tomasvana10 -qa "javascript,test " -onc 5 -po -o ..

Explanation:

1. Display the 5 oldest commits after querying the current repository's commits for either "javascript" OR "test "
2. Prevent the PDF directory from being automatically opened.
3. Output the PDF to the parent directory (..)

NOTE: -qa selects commits that include any query criteria in the title OR description, while -QA selects commits that include ALL query criteria in the title or description.

Advanced usage example #4

c2p tomasvana10 -QA "dev ,testing" -gen2a -sc 0.8

Explanation:

1. Query the repo for both "dev " AND "testing"
2. Use the gen2a PDF renderer to visualise the PDF
3. Set the scaling of the PDF output to 0.8

NOTE: Scaling (-sc) is only available when using gen2a or gen2b. gen2b is default.

Clone the repo you want to document on-demand:

c2p tomasvana10 -fc some_repo_name

Explanation: Create the repo you have specified and make the PDF. This repo is always cloned into the current working directory.

PDF Generation implementations

pycairo (gen1)

• Fast

• Looks like crap
• No hyperlinks, therefore the entire link to a commit's diff is displayed
• Occasional bugs in rendering

fpdf (gen2a)

• Fast
• Can be scaled with the -sc <float> 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 perfectly accurate page breaking

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

Gallery

gen1 title page

gen2 title page in dark mode

gen2 commit page in dark mode