Codebase Dump

A simple CLI tool to dump a project's structure and file contents into a single Markdown file. Ideal for providing context to LLMs, creating project snapshots, or generating documentation.

Features

• Project Tree Generation: Creates a visual tree of your project's directory structure.
• File Content Embedding: Includes the full content of specified file types.
• Advanced Exclusions: Exclude files and directories using .gitignore rules and custom glob patterns via pathspec.
• Rich Terminal Preview: Uses rich to show a colorful preview of the files that will be included in the dump.
• Clipboard Integration: Copies the entire dump to the clipboard instead of writing to a file.
• Highly Customizable: A wide range of CLI options to tailor the output to your needs.
• Built with Typer: Modern and easy-to-use CLI interface.

Installation

This tool is built and managed with uv, the fast Python package installer and resolver from Astral.

1. Install uv: If you don't have uv installed, follow the official installation guide:

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install codebase-dump: To make the codebase-dump command available globally, navigate to the root of this project and run:

   uv tool install .

   If uv warns that the tools directory is not in your PATH, follow the instructions it provides to update your shell configuration.

3. Update the tool: To update the tool after making changes to the source code, run:

   uv tool install . --force

Development Setup

To ensure code quality and consistency, this project uses pre-commit hooks for linting, formatting, type checking, and pytest for testing.

1. Sync Dependencies: Install all required dependencies for development:

   uv sync 

2. Install pre-commit Hooks: Set up the git hooks for automated checks on commit and push:

   pre-commit install
   pre-commit install --hook-type pre-push

   Now, ruff and ty will run automatically on every commit, and pytest will run on every push.

3. Run Tests: To run the tests manually:

   uv run pytest

4. Check Test Coverage: To run tests and check the test coverage:

   uv run pytest --cov=codebase_dump

   You can view a detailed HTML report by opening htmlcov/index.html.

Usage

Here are some common usage examples.

Basic Dump

This will scan the current directory for .py files and create a codebase.md file.

codebase-dump

Preview Included Files

Show a tree of the files that will be included in the output without writing the file.

codebase-dump --preview

Include More File Types

Include .toml and .md files in addition to the default .py.

codebase-dump --ext .py --ext .toml --ext .md

Specify Output File

Save the dump to a different file.

codebase-dump -o project_snapshot.md

Copy to Clipboard

Copy the entire dump to your clipboard.

codebase-dump --to-clipboard
# or
codebase-dump -c

Custom Exclusions

Exclude specific directories or files using glob patterns.

# Exclude the tests directory
codebase-dump -x "tests/*"

# Exclude all migration files
codebase-dump -x "*/migrations/*"

Disable .gitignore

To ignore the rules from your .gitignore file:

codebase-dump --no-gitignore

CLI Options

For a full list of commands and options, run:

codebase-dump --help