commits2pdf 1.1.5

View a filtered commit history in PDF form.

commits2pdf

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

Dependencies

pycairo
GitPython
fpdf

Installation

pip install commits2pdf or
pip3 install commits2pdf
If you encounter errors with building pycairo, click here

Command-line parameters

  -h, --help            show this help message and exit
  -O OWNER, --owner OWNER
                        The owner of the git repository. Required.
  -o OUTPUT, --output OUTPUT
                        Path to your PDF output. Set to "." by default.
  -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 the program 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

See usage info in the command-line: Run c2p -h

Simple usage:

c2p -O tomasvana10

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

Advanced usage example #1:

c2p -O 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 with the seriescalculator_sdd 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 -O 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 -O 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 -O 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 -O 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)

• Positives
  • Fast
• Negatives
  • Not scalable
  • Occasional rendering inconsistencies
  • Not as good looking at the other generation implementations
  • No hyperlinks
• Sample use case: You want to quickly generate a large amount of commits and do not care about the sizing of the PDF.

fpdf (gen2a)

• Positives
  • Fast
  • Scalable
  • Detailed title page
  • Sleek design
  • Hyperlinks
  • Creates metadata
• Negatives
  • Inconsistent page breaks (limitation with fpdf)
• Sample use case: You do not mind if your PDF has large gaps of space, but you want a nice design that can be generated very fast.

fpdf (gen2b - Default)

• Positives
  • Same as gen2a but with consistent page breaks that do not leave any whitespace
• Negatives
  • Slow (time complexity ranges between O(n) to O(n log n))
• Sample use case: You either want to visualise a relatively small amount of commits in a PDF that is sleek and consistently-designed
  
  

Gallery

gen1 title page

gen2 title page in dark mode

gen2 commit page in dark mode