Copcon 🐎

Copcon is a CLI tool that effortlessly copies your project's directory structure and file contents directly to the clipboard, ideal for working with AI chatbots.

Read the docs here

Overview

Copcon (Copy Context) is a CLI tool designed to generate a comprehensive report of a project's directory structure and file contents. This report can be used to provide context to large language models (LLMs) like ChatGPT, facilitating more informed and accurate responses based on your codebase.

Features

• Directory Tree Generation: Creates a visual representation of your project's directory structure.
• File Content Capture: Includes the contents of files, with options to handle binary files appropriately.
• Customizable Traversal Depth: Specify how deep the directory traversal should go.
• Exclusion Options: Exclude hidden files/directories and specify additional patterns to ignore.
• Clipboard Integration: Optionally copy the generated report directly to the clipboard.
• File Output: Save the report to a specified file instead of copying to the clipboard.
• Git Diff Integration:
  • Use the new -g (or --git-diff) flag to include the output of a git diff (showing changes since the last commit) in your context report.
  • The diff output is appended to the end of the report under a clear "Git Diff:" header.
  • Additionally, the token count for the git diff is calculated and included in the token distribution summary, so you can see how much of the overall token usage is consumed by the diff.

Installation

pip install copcon

Usage

After installation, use the copcon command to generate a report of your project.

Basic Command

Generate a report and copy it to the clipboard:

copcon /path/to/your/project

Options

• --depth INTEGER: Specify the depth of directory traversal (-1 for unlimited). Default is -1.
• --exclude-hidden / --no-exclude-hidden: Toggle exclusion of hidden files and directories. Default is --exclude-hidden.
• --ignore-dirs TEXT: Additional directories to ignore. Can be used multiple times.
• --ignore-files TEXT: Additional files to ignore. Can be used multiple times.
• --copconignore PATH: Path to a custom .copconignore file.
• --output-file PATH: Specify an output file path to save the report instead of copying to the clipboard.
• -g, --git-diff: Include the current git diff (changes since the last commit) in the context report.
  The git diff is appended to the report and its token count is included in the token distribution table.

Example Commands

Generate a Report with Default Settings (most commonly used)

copcon /path/to/your/project

Generate a Report with Custom Depth and Exclusions

copcon /path/to/your/project --depth 2 --ignore-dirs tests --ignore-files *.md

Output the Report to a File

copcon /path/to/your/project --output-file report.txt

Include Git Diff in the Report

copcon /path/to/your/project --git-diff

.copconignore Configuration

Copcon supports a .copconignore file to specify patterns for files and directories to exclude from the report. This file should be placed in the root of your project directory.

Syntax

The .copconignore follows the gitignore syntax, allowing for flexible pattern matching.

Example .copconignore:

# Ignore all log files
*.log

# Ignore the temp directory and all its contents
temp/

# Ignore all .tmp files in any directory
**/*.tmp

Report Format

Copcon generates a report structured into two main sections:

1. Directory Structure: A tree-like representation of your project's directories and files.
2. File Contents: The contents of each file, with binary files indicated appropriately.

Example Report:

Directory Structure:
your_project_name
├── folder1
│   ├── file1.py
│   └── file2.py
├── folder2
│   └── file3.py
└── main.py

File Contents:

File: folder1/file1.py
----------------------------------------
[Content of file1.py]
----------------------------------------

File: folder1/file2.py
----------------------------------------
[Content of file2.py]
----------------------------------------

File: folder2/file3.py
----------------------------------------
[Content of file3.py]
----------------------------------------

File: main.py
----------------------------------------
[Content of main.py]
----------------------------------------

Git Diff:
----------------------------------------
[Output of `git diff` will be appended here if the -g/--git-diff flag is used]
----------------------------------------

Platform Support

Copcon is compatible with the following operating systems:

• macOS
• Windows
• Linux (requires xclip or a similar package)

Linux Clipboard Support

To enable clipboard functionality on Linux, install xclip:

sudo apt install xclip

Development

Setting Up the Development Environment

1. Ensure you have Python 3.11+ and uv installed.

2. Clone the repository:

   git clone https://github.com/kasperjunge/copcon.git
   cd copcon
   

3. Install dependencies:

   uv sync
   

4. Run tests:

   uv run pytest
   

Contributing

Contributions are welcome. Please follow these steps to contribute:

1. Fork the repository.

2. Create a new branch for your feature or bugfix:

   git checkout -b feature/your-feature-name
   

3. Commit your changes with clear messages.

4. Push to your fork and submit a Pull Request.

Guidelines

• Adhere to PEP 8 coding standards.
• Include tests for new features or bug fixes.
• Update documentation as necessary.

License

This project is licensed under the MIT License.