repo2pdf: Convert a GitHub Repository Into a PDF

What repo2pdf actually does, and who it is for

The tool takes a repository, either a GitHub URL it clones or a path you already have on disk, and produces one PDF (or one PDF per file) containing the text of that repository. The README lists the intended uses as teaching, code reviews, offline referencing, archiving, AI training and document embedding. That list is honest about the appeal: a PDF is a format you can hand to someone who will not install a client, and it is a format that does not change under you.

The person this fits is not a developer browsing code day to day. It is someone assembling a reading copy: an instructor preparing printed examples, a reviewer who wants a single artifact attached to a ticket, or someone building a corpus of source text for later processing. If you want to read code, GitHub already does that better. repo2pdf is for producing a document.

The pipeline: clone, filter, highlight, render

The package metadata tells you most of the architecture. The entry point is dist/clone.js, built from TypeScript in src/, and the runtime dependencies are pdfkit for rendering, highlight.js for syntax colouring, simple-git for cloning, isbinaryfile for skipping binaries, strip-comments for the comment-removal option, inquirer and ora for the interactive prompts, and chalk for terminal output.

So the flow is sequential rather than streaming: obtain the working tree, walk it, decide per file whether it is text, optionally strip comments and blank lines, optionally tokenise it with highlight.js, and lay it out with pdfkit. There is no index, no database, no server component. The README points at clone.ts and syntax.ts as the files to edit for styling, which confirms that layout and highlighting are separate concerns in the source.

The filtering is the part worth understanding before you trust the output. The README states that certain file types and directories are ignored automatically, giving .png and .git as examples, and that you can extend the list with a repo2pdf.ignore file at the root of the repository. It also warns that for local repositories you may need to add more entries yourself, because the script does not automatically ignore different build files and directories. That is a real gap: a repository with a committed dist directory or a node_modules folder will put that content into the PDF unless you name it.

Installing repo2pdf and generating your first PDF

The README gives two installation paths. The quickest is npx, which downloads and runs the latest published version from the npm registry. Run it in an empty directory, because it clones into the working tree.

npx repo2pdf

The script then prompts for a GitHub repository URL, an output file name, and whether to keep the cloned repository. According to the README, you need Node greater than 18 and git installed for non-local repositories.

The second path is cloning the project itself and building it, which is what you want if you intend to change the styling. The README lists the steps in order.

git clone https://github.com/BankkRoll/repo2pdf
cd repo2pdf
npm install
npm run build
npm start

Running npm start executes node dist/clone.js, so the build step is not optional. When started this way the prompts are longer: it asks whether to clone a repository or use a local one, then walks a checklist of features (line numbers, page numbers, highlighting, removing comments, removing empty lines, one file or one PDF per file), then the output name, then whether to keep the clone.

To control what ends up in the document, add a repo2pdf.ignore file at the root of the repository being converted. The README shows this shape:

{
  "ignoredFiles": ["tsconfig.json", "dist", "node_modules"],
  "ignoredExtensions": [".raw"]
}

The two keys are ignoredFiles and ignoredExtensions. Note the README's caveat that for a local repository this file must sit in the root of that repository directory, not in the repo2pdf checkout.

Where repo2pdf breaks down

The README is explicit that only text-based files are converted and that binary files such as images or compiled binaries are ignored. That is a deliberate limit, and it means the PDF is not a faithful archive of a repository. A project whose meaning lives in diagrams, fixtures, images or generated assets will lose them silently. You get no visual placeholder in the PDF telling you something was skipped, at least not according to the documentation.

The ignore defaults are the second weak point, and the README admits it. Because the tool does not automatically exclude build output, a large repository can produce a PDF padded with minified bundles and dependency trees. The ignore file is the fix, but it is manual and per-repository, which means the quality of the output depends on how carefully you configure it.

The third issue is scale. Everything is rendered through pdfkit in a single process. The README does not document any size limit, memory profile or streaming behaviour, and there are no published benchmarks, so the honest position is that the documentation is silent on how the tool behaves on a very large repository. If you are converting a monorepo, test on a subset first rather than assuming it will finish.

Finally, there is no rollback story. The README documents a prompt asking whether to keep the cloned repository, but nothing about resuming a partial run or cleaning up after an interrupted one. If the process fails midway, you handle the leftover directory yourself.

repo2pdf compared with text-dump alternatives

The searches around this project mix it up with Git2pdf, Gitprint, Git2text and generic "local directory to plain text" tools, and the distinction matters. Git2text and similar utilities flatten a repository into a single plain-text or markdown blob, usually to paste into a language model context window. repo2pdf produces a paginated PDF instead.

That difference drives everything else. A text dump is cheap to produce, trivially diffable and easy to pipe into another program. A PDF gives you pagination, line numbers, page numbers and syntax colouring, which is what you want when a human reads the result on paper or in a PDF viewer. It also makes the output harder to reuse programmatically.

If your goal is to feed source into a model, the plain-text approach is the better fit and repo2pdf is the wrong tool. If your goal is a document a person will read, the reverse holds. The project's own keyword list includes langchain and openai, which suggests AI-adjacent use, but the artifact it produces is a PDF, and that is the constraint to design around.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-06-02. The published version in package.json is 2.2.9, and the package declares engines.node as >=18.0.0. There are no retrieved releases, so version history is not visible from the release feed; the npm version field is the reference point.

The licence is MIT, stated in the README badge and in package.json. MIT is permissive: it allows use, modification and redistribution provided the copyright notice and licence text are retained. That is the general shape of the licence, not legal advice, and anyone embedding the output in a commercial product should read LICENSE.md themselves.

The upgrade cost is low in the normal case, because npx always fetches the latest published version and there is no service to migrate. The cost is higher if you have edited clone.ts or syntax.ts for styling, since the README presents that as the supported way to customise the PDF and a rebuild will not merge your changes. The test script in package.json is a placeholder that echoes an error and exits non-zero, so there is no test suite to catch a regression in your local modifications.

Answers to the questions people actually ask

The recurring questions around repo2pdf are about converting a repository to PDF, which is the tool's whole purpose, and about the online route. The README points to a web app at repo2pdf.site as a newer option, alongside the npx and clone-and-build paths. There is no documented difference in output between the web app and the CLI, so if the result matters to you, verify it against the CLI on the same repository.

The other common question is how to include line numbers, and the answer is a prompt rather than a flag. The README states that during execution you are asked "Include line numbers?" and answering Y adds them. The same applies to page numbers, highlighting, comment removal, empty-line removal and the one-file-per-PDF choice. Because these are interactive prompts, repo2pdf is awkward to script, and the README does not document an environment variable or command-line flag that bypasses them.

Editorial conclusion

Use repo2pdf if you need a fixed, offline snapshot of a text-only repository and you are comfortable reading src/clone.ts to change anything about the output. Do not use it if the repository contains notebooks, images, generated bundles or more than a few thousand files, and do not treat the PDF as a byte-faithful copy of the source. Before adopting it, run npx repo2pdf against a small public repository and open the resulting PDF, then check the repo2pdf.ignore file at the root of the repository you are converting, since the tool only auto-ignores common binary types and leaves build output such as dist and node_modules to you.

Frequently asked questions

Official sources

1. BankkRoll/repo2pdf on GitHub
2. Issues
3. License: MIT
4. Project website
5. README