Getting Started with Copcon

Introduction

Welcome to Copcon! This guide will walk you through installing and using Copcon—a CLI tool that generates a detailed report of your project’s directory structure and file contents. Whether you need context for an AI chatbot or simply want to document your project, Copcon makes it easy.

Installation

Before you begin, ensure you have Python 3.11 or later installed. Then, install Copcon using pip:

pip install copcon

Basic Usage

After installation, you can run Copcon directly from your terminal. The most basic usage is as follows:

copcon /path/to/your/project

This command generates a report of your project and copies it directly to your clipboard.

Step-by-Step Guide

Navigate to Your Project Directory

Open your terminal and change to the directory where your project is located:
```
cd /path/to/your/project
```
Generate a Report and Copy to Clipboard

Run the command below to generate a report of your project. The report will automatically be copied to your clipboard:
```
copcon .
```
Limit Directory Traversal Depth

If you want to limit how deep Copcon traverses your directory structure, use the --depth option. For example, to traverse only two levels deep:
```
copcon . --depth 2
```
Control Hidden Files and Directories

By default, Copcon excludes hidden files and directories. If you wish to include them, use the --no-exclude-hidden flag:
```
copcon . --no-exclude-hidden
```
Using Ignore Patterns

Copcon automatically applies ignore patterns from a .copconignore file (using gitignore syntax). If no such file is found, internal default patterns are used. Customize this file in your project to exclude specific files or directories.
Output the Report to a File

Instead of copying the report to your clipboard, you can save it to a file using the --output-file option:
```
copcon . --output-file report.txt
```
Include Git Diff in the Report

To append the output of git diff (showing changes since the last commit) to your report, use the -g or --git-diff flag:
```
copcon . --git-diff
```
The git diff output will be appended at the end of the report, and its token count will be included in the summary.

Summary

Copcon is a powerful tool that simplifies generating detailed project reports. With flexible options for depth control, hidden file handling, ignore patterns, file output, and git diff integration, it’s designed to fit a wide range of workflows.

Next Steps

For further details, check out the following sections: - CLI Documentation: See Command Line Interface (CLI) for complete command options. - Core Modules: See Core Modules for advanced topics such as file filtering, report formatting, and more. - Utilities: See Utils for additional tools and logging details.

Happy coding!