Skip to main content

​
Converting Remote Repositories

The primary use case for repo2pdf is converting remote GitHub repositories into well-formatted PDF documents. When you run the tool, it guides you through an interactive configuration process.

​
Quick Start

Simply run the command to start the interactive setup: 
repo2pdf
You’ll be greeted with the repo2pdf banner and a series of prompts: 
  ██████╗ ███████╗██████╗  ██████╗         ██████╗         ██████╗ ██████╗ ███████╗
  ██╔══██╗██╔════╝██╔══██╗██╔═══██╗        ╚════██╗        ██╔══██╗██╔══██╗██╔════╝
  ██████╔╝█████╗  ██████╔╝██║   ██║         █████╔╝        ██████╔╝██║  ██║█████╗
  ██╔══██╗██╔══╝  ██╔═══╝ ██║   ██║        ██╔═══╝         ██╔═══╝ ██║  ██║██╔══╝
  ██║  ██║███████╗██║     ╚██████╔╝        ███████╗        ██║     ██████╔╝██║
  ╚═╝  ╚═╝╚══════╝╚═╝      ╚═════╝         ╚══════╝        ╚═╝     ╚═════╝ ╚═╝

  Welcome to Repo-to-PDF! Let's get started...

​
Step-by-Step Process

1

Choose Repository Type

When asked “Do you want to use a local repository?”, select No to clone a remote GitHub repository.
? Do you want to use a local repository? (Use arrow keys)
❯ No
  Yes
2

Provide GitHub URL

Enter a valid GitHub repository URL in the format https://github.com/owner/repo.
? Please provide a GitHub repository URL: https://github.com/username/my-project
The URL must match the pattern https://github.com/[owner]/[repo] - other Git hosting services are not currently supported.
3

Select Features

Choose which features to include in your PDF using the spacebar to select/deselect:
? Select the features you want to include: (Press <space> to select, <a> to toggle all)
❯ ◯ Add line numbers
  ◯ Add highlighting
  ◯ Add page numbers
  ◯ Remove comments
  ◯ Remove empty lines
  ◯ One PDF per file
See Configuration for detailed feature descriptions.
4

Set Output Name

Specify the output filename for your PDF:
? Please provide an output file name: (output.pdf)
This prompt only appears when One PDF per file is not selected. The default is output.pdf.
5

Keep or Delete Repository

Decide whether to keep the cloned repository after PDF generation:
? Do you want to keep the cloned repository? (Use arrow keys)
❯ No
  Yes
The repository is cloned to a temporary directory called tempRepo by default.

​
Processing Output

Once configured, repo2pdf will:
  1. Clone the repository to a temporary directory
  2. Process all files according to your selected features
  3. Generate the PDF(s)
  4. Optionally clean up the temporary repository
✔ Setting everything up
✔ Repository cloned successfully
✔ Processing files... (47 processed)
✔ PDF created with 47 files processed.
✔ Temporary repository has been deleted.

​
What Gets Included

By default, repo2pdf includes all text-based files in your repository while automatically excluding:

​
Excluded Files

  • .gitignore, .gitmodules
  • package-lock.json, yarn.lock
  • .git directory
  • .vscode, .idea, .vs (IDE directories)
  • node_modules
  • repo2pdf.ignore

​
Excluded Extensions

  • Image files: .png, .jpg, .jpeg, .gif, .svg, .bmp, .webp, .ico
  • Video files: .mp4, .mov, .avi, .wmv
  • YAML files: .yml
  • PDF files: .pdf
You can customize these exclusions using a repo2pdf.ignore file. See Configuration for more details.

​
Binary Files

Binary files that aren’t excluded will be included in the PDF as base64-encoded strings: 
path/to/binary-file.bin

BASE64:

QmluYXJ5IGNvbnRlbnQgZW5jb2RlZCBpbiBiYXNlNjQ=

​
Repository Validation

The GitHub URL must be a valid repository URL. The tool validates:
  • Protocol must be https://
  • Domain must be github.com
  • Path must follow the pattern /owner/repo
Private repositories require authentication. Ensure you have Git credentials configured on your system or use a local repository approach.

​
Next Steps

Local Repositories

Use local repositories instead of cloning

Configuration

Explore all available features and options

Output Options

Learn about different PDF output modes

Installation

Installation requirements and setup