Forked from BankkRoll/repo2pdf
This fork replaces the interactive question-and-answer CLI with a non-interactive, flag-based interface. The goal is to support automation, CI/CD pipelines, and scripting scenarios where interactive prompts are impractical or impossible.
The upstream project remains excellent for exploratory use and users who prefer guided setup. This fork prioritizes deterministic, reproducible execution with explicit command-line arguments.
Use this fork if you need:
- CI/CD pipelines generating documentation artifacts
- Scripts that batch-convert multiple repositories
- Automation workflows requiring deterministic, reproducible output
- Explicit flags over interactive prompts
Use upstream if you prefer:
- Guided, step-by-step configuration
- Interactive terminal workflows
- Exploring available options through prompts
$ npx repo2pdf-cli
? Do you want to use a local repository? Yes
? Please provide the full path to the local repository: /path/to/repo
? Select the features you want to include: Add line numbers, Add highlighting
? Please provide an output file name: output.pdf
npx repo2pdf-cli /path/to/repo --line-numbers -o output.pdfSingle command. No prompts. Scriptable.
repo2pdf-cli can be installed by either directly using NPX or cloning the repository from GitHub.
This method downloads and installs the latest version of repo2pdf-cli from the NPM registry.
The simplest way to use repo2pdf-cli is to provide just the path to your local repository. By default, it will:
- Enable syntax highlighting
- Remove comments
- Remove empty lines
- Generate a PDF with the same name as the repository
npx repo2pdf-cli /path/to/your/repositoryFor example:
npx repo2pdf-cli /path/to/my-projectThis will create my-project.pdf in your current directory.
You can customize the behavior using command-line flags:
npx repo2pdf-cli [options] <path>Available Options:
-o, --output <filename>- Specify custom output filename--no-highlighting- Disable syntax highlighting--keep-comments- Keep comments in the code--keep-empty-lines- Keep empty lines in the code--line-numbers- Add line numbers to the PDF--page-numbers- Add page numbers to the PDF--one-pdf-per-file- Generate one PDF per file--output-folder <folder>- Output folder for one-pdf-per-file mode--include-hidden- Include hidden files (files starting with.)
Examples:
# Custom output filename
npx repo2pdf-cli /path/to/repo -o my-project.pdf
# Add line numbers and page numbers
npx repo2pdf-cli /path/to/repo --line-numbers --page-numbers
# Keep comments and empty lines
npx repo2pdf-cli /path/to/repo --keep-comments --keep-empty-lines
# Disable highlighting and add line numbers
npx repo2pdf-cli /path/to/repo --no-highlighting --line-numbers
# Generate one PDF per file
npx repo2pdf-cli /path/to/repo --one-pdf-per-file --output-folder ./pdfsThis method involves manually cloning the repo2pdf-cli repository and setting it up on your local machine.
- Clone the repository:
git clone https://github.com/liberzon/repo2pdf- Navigate to the repo2pdf directory:
cd repo2pdf- Install the dependencies:
npm install- Build the script:
npm run build- Run the CLI:
# Using the cli alias with arguments
npm run cli -- /path/to/your/repository
# With options
npm run cli -- /path/to/repo --line-numbers -o output.pdf
# Or use npm start (legacy method)
npm startExamples:
# Basic usage
npm run cli -- /path/to/my-project
# With custom output and options
npm run cli -- /path/to/repo -o custom.pdf --line-numbers --page-numbers
# Show help
npm run cli -- --helpPlease note that you need to have Node >= 18 installed on your system in order to run repo2pdf-cli.
repo2pdf-cli automatically ignores certain file types and directories (e.g., .png, .git).
Hidden files and directories (those starting with .) are also ignored by default. Use --include-hidden to include them.
To customize the files and directories to ignore, you can add a repo2pdf.ignore file.
The tool searches for repo2pdf.ignore in the following order:
- Current working directory (where you run the command) - Use this for project-specific ignore rules
- Target repository directory (the directory being converted) - Falls back to this if not found in current directory
- Package installation directory (where repo2pdf-cli is installed) - Use this for global default ignore rules
This allows you to:
- Maintain a common ignore configuration in your working directory that applies to all repositories you convert
- Use repository-specific ignore files
- Set up global defaults in the package installation directory
Example:
# If you're in /Users/you/projects and run:
npx repo2pdf-cli /path/to/repo
# It will look for:
# 1. /Users/you/projects/repo2pdf.ignore (current directory - preferred)
# 2. /path/to/repo/repo2pdf.ignore (target directory - fallback)
# 3. <package-install-dir>/repo2pdf.ignore (package directory - global default){
"ignoredFiles": [
"tsconfig.json",
"dist",
"node_modules",
"coverage",
".env",
".vscode",
"CHANGELOG.md"
],
"ignoredExtensions": [
".log",
".raw",
".map",
".min.js",
".min.css"
]
}Fields:
ignoredFiles: Array of file or directory names to exclude (matches exact basename)ignoredExtensions: Array of file extensions to exclude (include the leading dot)
Q: Why is this a fork instead of a contribution to upstream?
The upstream project is designed around an interactive, prompt-based UX. Replacing that with a flag-based CLI is a fundamental change to the user experience, not a bug fix or incremental feature. Rather than proposing a breaking change that might not align with upstream's goals, this fork rebuilds the CLI layer while keeping the core PDF generation logic intact.
If upstream maintainers are interested in adopting this approach or merging portions of it, that conversation is welcome.
Q: I'm getting an error "Failed to install [package-name]". What should I do?
A: Make sure you have Node.js and npm installed on your system. Try running the following command to install the required package manually:npm install [package-name]Q: How can I customize the styling of the generated PDF?
A: You can modify the code in `clone.ts` or `syntax.ts` to change the font, font size, colors, and other styling options for the PDF document.// Example: Changing font size in syntax.ts
doc.fontSize(12);Q: What types of files are supported for conversion to PDF?
A: Currently, repo2pdf-cli supports all text-based files for conversion to PDF. Binary files like images or compiled binaries are ignored.Q: How can I modify the ignored files list?
A: You can add a `repo2pdf.ignore` file in either your current working directory (preferred) or in the target repository directory. The tool checks the current directory first, then falls back to the target directory. Here's an example of how to structure this file:{
"ignoredFiles": ["tsconfig.json"],
"ignoredExtensions": [".md"]
}Q: How can I include line numbers in the generated PDF?
A: Use the `--line-numbers` flag when running the command:npx repo2pdf-cli /path/to/repo --line-numbersQ: How can I generate a PDF for a local repository?
A: Simply provide the path to your local repository as the first argument:npx repo2pdf-cli /path/to/your/local/repoQ: Can I keep comments in the code?
A: Yes! By default, comments are removed. To keep them, use the `--keep-comments` flag:npx repo2pdf-cli /path/to/repo --keep-commentsContributions are welcome! Here's how you can help:
- Open an issue on GitHub detailing the bug.
- Describe the problem in depth. Share the steps to reproduce the issue and any error messages you received.
- If possible, provide information about your operating system and Node.js version.
- Open an issue on GitHub to share your suggestions.
- Be as detailed as possible, explaining what you want to achieve and why it would be beneficial to the project.
- Fork the repository.
- Create a new branch for your changes.
- Make your changes in your branch.
- Submit a pull request from your branch to the main repo2pdf-cli repository.
In your pull request, please provide a clear description of the changes you've made.
repo2pdf-cli is open source software, licensed under the MIT License. See the LICENSE file for more information.