https://github.com/tomasvana10/commits2pdf
Convert Git commits to a PDF
https://github.com/tomasvana10/commits2pdf
cli commits git multimedia pdf pycairo python-package python3
Last synced: 8 months ago
JSON representation
Convert Git commits to a PDF
- Host: GitHub
- URL: https://github.com/tomasvana10/commits2pdf
- Owner: tomasvana10
- License: mit
- Created: 2024-03-28T10:07:40.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-07-05T13:08:43.000Z (almost 2 years ago)
- Last Synced: 2025-09-25T12:36:06.381Z (9 months ago)
- Topics: cli, commits, git, multimedia, pdf, pycairo, python-package, python3
- Language: Python
- Homepage:
- Size: 539 KB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# commits2pdf
[](https://pypi.org/project/commits2pdf/)
[](https://github.com/tomasvana10/commits2pdf/actions/workflows/publish.yml)
[](https://github.com/tomasvana10/commits2pdf/releases/latest)
[](https://github.com/tomasvana10/commits2pdf/issues)
[](https://github.com/tomasvana10/commits2pdf/actions/workflows/github-code-scanning/codeql)
[](https://github.com/tomasvana10/commits2pdf/actions/workflows/tox-tests.yml)
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](https://pip.pypa.io/en/stable/installation/)** to install it.
> If you do not have Python installed, download the installer **[here](https://www.python.org/downloads/)**, then refer to the previous link on how to install pip.
> Additionaly, `commits2pdf` requires Git for `gitpython` functionality. Install it **[here](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)**.
> [!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](#changing-your-terminals-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](https://stackoverflow.com/a/76175684/23245953)**
## 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`.
3. (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)
Positional Flags
`owner` : The owner of the git repository. Required.
Optional Flags
`-o`, `--output` : Directory path to your PDF output. Set to `.` (your current directory) by default. Will be created if it does not exist. Example: `./work/my_pdfs`
`-n`, `--name` : The name of your outputted PDF file. Set to `-commit_report` by default.
`-b`, `--branch` : The repository branch. Set to `main` by default.
`-a`, `--authors` : Filter commits from a comma-separated list of authors. Format: `` OR `` etc. Set to `all authors` by default.
`-s`, `--start-date` : Filter from start date of commits. Format: `d/m/YYYY`. Example: `5/12/2023`
`-e`, `--end-date` : Filter to end date of commits. Format: `d/m/YYYY`. Example: `5/12/2023`
`-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` : Set the scaling of the output PDF. Only available with `-gen2a` and `-gen2b`.
`-in`, `--include` : Include commits with the given string sequences in their title or description. Format: `` OR ``. Whitespace sensitive and case insensitive. NOTE: This query is performed BEFORE excluding commits.
`-ex`, `--exclude` : Exclude commits with the given string sequences in their title or description. Format: `` OR ``. Whitespace sensitive and case insensitive.
`-q`, `--quiet` : Suppress all logger messages except for errors.
`-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 `fpdf`. The default option.
`-rp`, `--repo-path` : Path to your repository directory. Set to `.` (your current directory) by default.
`-fc`, `--repo-from-clone` : Clone a repo into the working directory and generate the commits PDF from it automatically. Format: `` (case insensitive).
`-nc`, `--newest-n-commits` : Select the newest n number amount of commits to include after filtering.
`-oc`, `--oldest-n-commits` : Select the oldest n number amount of commits to include after filtering.
## 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)