Basic Usage

Learn how to convert GitHub repositories to PDF documents

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