View a filtered commit history in PDF form.
Project description
commits2pdf
Visualise a GitHub repo'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 WINDOW: venv\scripts\activate
Install the package:
pip install commits2pdf OR pip3 install commits2pdf
Scroll down for usage information.
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: <author@email.com> OR <author1@email.com,author2@email.com> 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 person@email.com,other_person@gmail.com -s 2024-11-30 -e 2024-12-30 -b other_branch -d
Explanation:
- Override the default repository path with the
seriescalculator_sdd
folder in the parent directory - Look for specific commit emails (separated by commas)
- Search for commits from the -s date until the -e date
- Search for commits only made to
other_branch
- 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:
- Display the 5 oldest commits after querying the current repository's commits for either "javascript" OR "test "
- Prevent the PDF directory from being automatically opened.
- 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:
- Query the repo for both "dev " AND "testing"
- Use the
gen2a
PDF renderer to visualise the PDF - 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
- Saves metadata
- Negatives
- Inconsistent page breaks in some cases due to the difficulty of precalculating the height of a commit, a general limitation with this generation method.
- Sample use case: You do not mind if your PDF has occasionally inconsistent spacing, 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 when generating large
- Sample use case: You 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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for commits2pdf-1.1.7-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2f9d64e2dabeefe696bc65e64d0110f98848922a7c1884d2b5e7349ec63b231d |
|
MD5 | ca9b760d54427ddf9b92170b1fc4a501 |
|
BLAKE2b-256 | 9c2ea634ea058810a87f569285f7817c00a64c403d807760a0114cae7143001e |