<div align="center">
# 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)
</div>
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.<br><br>
> 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.<br><br>
> 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`.
- 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).
```
pip install virtualenv
python -m venv venv
MacOS/Unix: source venv/bin/activate
Windows: venv\scripts\activate
```
- 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
```
- 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 <folder name> as Pathname`
Then, in your terminal, run `cd <the path you copied>` (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)
<details><summary>Positional Flags</summary>
`owner` : The owner of the git repository. Required.
</details>
<details><summary>Optional Flags</summary>
`-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 `<repo_name>-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: `<author@email.com>` OR `<author1@email.com,author2@email.com>` 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: `<string1>` OR `<string1,string2>`. 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: `<string1>` OR `<string1,string2>`. 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: `<repo name>` (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.
</details>
## 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`).
<br>**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.
<br>**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".
<br>**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 <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 accurate page breaking
👎 Slow when generating large amounts of commits (generally, it is a good idea to enable `-gen2a` when drawing over 5000 commits)
Raw data
{
"_id": null,
"home_page": "https://github.com/tomasvana10/commits2pdf",
"name": "commits2pdf",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Tomas Vana",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ac/97/e43bd69d4bd5a3dc11812a9bed95be3fd8519d896729df5c35e8fb7c3eb1/commits2pdf-1.1.16.tar.gz",
"platform": "any",
"description": "<div align=\"center\">\n\n # commits2pdf\n \n [](https://pypi.org/project/commits2pdf/)\n [](https://github.com/tomasvana10/commits2pdf/actions/workflows/publish.yml)\n [](https://github.com/tomasvana10/commits2pdf/releases/latest)\n [](https://github.com/tomasvana10/commits2pdf/issues)\n [](https://github.com/tomasvana10/commits2pdf/actions/workflows/github-code-scanning/codeql)\n [](https://github.com/tomasvana10/commits2pdf/actions/workflows/tox-tests.yml)\n\n</div>\n\nVisualise a Git repository's commit history in PDF form via the command-line\n\n\n\n## Dependencies\n`GitPython` `fpdf` `progressbar` `pathvalidate`\n\n`pycairo` (used for deprecated PDF generation method, must be installed manually)\n\n## Installation\n> [!IMPORTANT]\n> Installing `commits2pdf` requires Python and pip.\n> If you have Python installed without pip, click **[here](https://pip.pypa.io/en/stable/installation/)** to install it.<br><br>\n> 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.<br><br>\n> Additionaly, `commits2pdf` requires Git for `gitpython` functionality. Install it **[here](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)**.\n\n> [!TIP]\n> If using `python` or `pip` doesn't work, try using `python3` or `pip3`.\n\n- Make a virtual environment and activate it (recommended):\n\n - 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).\n```\npip install virtualenv\npython -m venv venv\nMacOS/Unix: source venv/bin/activate\nWindows: venv\\scripts\\activate\n```\n- Install the package in your system directory/virtual environment:\n```\npip install -U commits2pdf\n```\nor, install the package in your home directory if you aren't using a virtual environment:\n```\npip install --user -U commits2pdf\n```\n- You can deactivate your virtual environment when you are done:\n```\ndeactivate\n```\n\n> [!TIP]\n> **If you encounter errors with building `pycairo`, click [here](https://stackoverflow.com/a/76175684/23245953)**\n\n## Changing your terminal's directory\n1. Open your terminal\n2. Find your repository's folder\n3. (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`.\n3. (b) On MacOS: Right click on the folder, hold `option` (`\u2325`) and click `Copy <folder name> as Pathname`\n\nThen, in your terminal, run `cd <the path you copied>` (paste in the path with `CTRL+V` or `CMD+V`).\n\n## Command-line parameters\nThere 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)\n\n<details><summary>Positional Flags</summary>\n\n`owner` : The owner of the git repository. Required.\n\n</details>\n\n<details><summary>Optional Flags</summary>\n \n `-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 \n `-n`, `--name` : The name of your outputted PDF file. Set to `<repo_name>-commit_report` by default.\n \n `-b`, `--branch` : The repository branch. Set to `main` by default.\n \n `-a`, `--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.\n \n `-s`, `--start-date` : Filter from start date of commits. Format: `d/m/YYYY`. Example: `5/12/2023`\n \n `-e`, `--end-date` : Filter to end date of commits. Format: `d/m/YYYY`. Example: `5/12/2023`\n \n `-r`, `--reverse` : Output the commits from newest to oldest. Set to `oldest to newest` by default\n \n `-d`, `--dark` : Toggle dark mode for the output PDF. Set to `light` by default.\n \n `-po`, `--prevent-open` : Prevent commits2pdf from automatically opening the directory the PDF was created in.\n \n `-sc`, `--scaling` : Set the scaling of the output PDF. Only available with `-gen2a` and `-gen2b`.\n \n `-in`, `--include` : Include commits with the given string sequences in their title or description. Format: `<string1>` OR `<string1,string2>`. Whitespace sensitive and case insensitive. NOTE: This query is performed BEFORE excluding commits.\n \n `-ex`, `--exclude` : Exclude commits with the given string sequences in their title or description. Format: `<string1>` OR `<string1,string2>`. Whitespace sensitive and case insensitive.\n \n `-q`, `--quiet` : Suppress all logger messages except for errors.\n \n `-gen1`, `--pdf-gen-1 ` : PDF rendering implementation with `pycairo`.\n \n `-gen2a`, `--pdf-gen-2a` : The first PDF rendering implementation with `fpdf`.\n \n `-gen2b`, `--pdf-gen-2b` : The second PDF rendering implementation with `fpdf`. The default option.\n \n `-rp`, `--repo-path` : Path to your repository directory. Set to `.` (your current directory) by default.\n \n `-fc`, `--repo-from-clone` : Clone a repo into the working directory and generate the commits PDF from it automatically. Format: `<repo name>` (case insensitive).\n \n `-nc`, `--newest-n-commits` : Select the newest n number amount of commits to include after filtering.\n \n `-oc`, `--oldest-n-commits` : Select the oldest n number amount of commits to include after filtering.\n\n</details>\n\n## Usage\n\n> [!TIP]\n> If the value you are providing for a given argument/flag includes spaces, wrap in it quotations (\"\") to ensure it is parsed properly.\n\n**Usage example #1**\n```\nc2p tomasvana10\n```\n> Output a PDF to your current directory (assuming it is a git repository that is owned by `tomasvana10`).\n\n<br>**Usage example #2**\n```\nc2p tomasvana10 -o .. -rp ./my_repo -n \"new_name.pdf\"\n```\n> 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.\n\n<br>**Usage example #3**\n```\nc2p tomasvana10 -nc 10 -in \"javascript,build\" -ex \"testing\"\n```\n> 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\".\n\n<br>**Usage example #4**\n```\nc2p devguarv -fc Yr-12-HSC-SDD-Task-2 -e 28/4/2024\n```\n> 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`.\n\n## PDF generation implementations\n### pycairo (gen1 - deprecated)\n\ud83d\udc4d Fast\n\n\ud83d\udc4e Cannot write multipage commits\n\n\ud83d\udc4e Looks like crap\n\n\ud83d\udc4e No hyperlinks, therefore the entire link to a commit's diff is displayed\n\n### fpdf (gen2a)\n\ud83d\udc4d Fast\n\n\ud83d\udc4d Can be scaled with the `-sc <float>` argument<\n\n\ud83d\udc4d Sleek design\n\n\ud83d\udc4d Information title page\n\n\ud83d\udc4d Contains hyperlinks\n\n\ud83d\udc4d Stores PDF metadata\n\n\ud83d\udc4e Inconsistent page breaks, a general limitation with FPDF when trying to fit as many whole commits on a single page\n\n### fpdf (gen2b - Default)\n\ud83d\udc4d Same as `gen2a` but with accurate page breaking\n\n\ud83d\udc4e Slow when generating large amounts of commits (generally, it is a good idea to enable `-gen2a` when drawing over 5000 commits)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Convert Git commits to a PDF",
"version": "1.1.16",
"project_urls": {
"Homepage": "https://github.com/tomasvana10/commits2pdf"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d29fa2c788ef9a8327e2dd097e7fe496705006181e325b0debbc38ec07ce3477",
"md5": "c5583129534fed1e97556187c9c208ab",
"sha256": "af88b1c35d6c606101be9317036eda1955dbadc40272f85f1deebfcc555b9a48"
},
"downloads": -1,
"filename": "commits2pdf-1.1.16-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c5583129534fed1e97556187c9c208ab",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 20749,
"upload_time": "2024-05-28T09:28:52",
"upload_time_iso_8601": "2024-05-28T09:28:52.716532Z",
"url": "https://files.pythonhosted.org/packages/d2/9f/a2c788ef9a8327e2dd097e7fe496705006181e325b0debbc38ec07ce3477/commits2pdf-1.1.16-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ac97e43bd69d4bd5a3dc11812a9bed95be3fd8519d896729df5c35e8fb7c3eb1",
"md5": "11628e666c7fd79d31543d4b987261cc",
"sha256": "72609084bae8b2c69b36f051ed938da95a5091e62bfc662840a5297f13efeba3"
},
"downloads": -1,
"filename": "commits2pdf-1.1.16.tar.gz",
"has_sig": false,
"md5_digest": "11628e666c7fd79d31543d4b987261cc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 20522,
"upload_time": "2024-05-28T09:28:53",
"upload_time_iso_8601": "2024-05-28T09:28:53.973183Z",
"url": "https://files.pythonhosted.org/packages/ac/97/e43bd69d4bd5a3dc11812a9bed95be3fd8519d896729df5c35e8fb7c3eb1/commits2pdf-1.1.16.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-28 09:28:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tomasvana10",
"github_project": "commits2pdf",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "commits2pdf"
}
JSON
