A tool to generate comprehensive Markdown artifacts of directory structures and file contents
Project description
CodeMapper
Overview
CodeMapper is a powerful Python tool designed to generate comprehensive Markdown (pdf, xml, and json outputs are on the way) representations of codebases. It bridges the gap between human developers and AI systems by providing a clear, structured view of project architectures and their complete contents. Whether you're working with local directories or GitHub repositories, CodeMapper creates a single, navigable document that encapsulates the full structure and content of a project.
This tool is invaluable for rapid codebase comprehension, whether you're a developer onboarding to a new project or an AI system analyzing code structure.
For audio explanations of this project, see:
- podcasts (Auto-generated by Gemini using NotebookLLM)
Features
- Dual-Purpose Output: Generates content optimized for both human readers and AI analysis
- Intelligent Content Parsing:
- Respects
.gitignore
rules - Handles various file types appropriately
- Respects
- Comprehensive Structure Representation:
- Creates an accurate, hierarchical file tree
- Generates a smart table of contents for easy navigation
- Code-Aware Processing:
- Applies appropriate syntax highlighting for different file types
- Intelligently handles large or binary files without bloating the output
- Flexible Input Handling: Works with local directories and GitHub repositories
- Encoding Detection: Ensures accurate content reading across various file encodings
- Customizable Ignore Rules: Option to include files normally ignored by
.gitignore
- Efficient Output Management: Organizes generated documents in a '_codemaps' directory
Roadmap
Requirements
- Python 3.6+
pathspec
library (for handling.gitignore
rules)chardet
library (for file encoding detection)
Installation
From PyPI
Install CodeMapper directly from PyPI using pip:
pip install codemapper
From Source
-
Clone this repository:
git clone https://github.com/shaneholloman/codemapper.git
-
Navigate to the cloned directory and install the required dependencies:
cd codemapper pip install -r requirements.txt
Usage
Run CodeMapper from the command line, providing the path to the directory or GitHub repository URL you want to analyze:
codemapper <path_to_directory_or_github_url> [--include-ignored]
Options
<path_to_directory_or_github_url>
: The path to the directory or GitHub repository URL to analyze (required)--include-ignored
: Include files that are normally ignored by.gitignore
(optional)
Output
CodeMapper generates a Markdown file named <directory_name>_codemap.md
in the '_codemaps' directory. This file contains:
- A comprehensive table of contents for easy navigation
- An accurate file tree representation of the directory structure
- The contents of each file, formatted with appropriate syntax highlighting
- Information about large and binary files (type and size) without their contents
Example usage and output:
codemapper https://github.com/shaneholloman/ansible-role-apache
Use Cases
- Rapidly understand the structure and content of new or unfamiliar projects
- Generate comprehensive documentation for code-based AI prompts
- Facilitate thorough code reviews by providing a complete one-page overview
- Assist AI systems in analyzing and understanding complex codebases
- Analyze GitHub repositories without manual cloning
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- Thanks to the
pathspec
andchardet
libraries for enhancing CodeMapper's functionality.
Version History
For a detailed version history, please refer to the changelog.md.
If you find CodeMapper useful, don't forget to star this repository!
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file codemapper-3.7.0.tar.gz
.
File metadata
- Download URL: codemapper-3.7.0.tar.gz
- Upload date:
- Size: 13.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.11.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | d8e9aa21f08db7e249449ca9af232acd05f619db31f2d47eb0d3ff2f10a0e067 |
|
MD5 | 0ae6fc0dd37c1575ae7674a50d66cb42 |
|
BLAKE2b-256 | 260e2c42a035aeac79d57bbc3587d08740c644740eab4d279e3a558ac08532af |
Provenance
File details
Details for the file codemapper-3.7.0-py3-none-any.whl
.
File metadata
- Download URL: codemapper-3.7.0-py3-none-any.whl
- Upload date:
- Size: 12.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.11.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 277dc63787316cd500fd06fc9d008b535311bcaf252dd2f0cc92327cba87e4b8 |
|
MD5 | eb31443879cbe9212d50a0a2baade1f6 |
|
BLAKE2b-256 | 0926282043f8e7f0977f9b84818a9b25b74c61bdf88adbc1b7d3e3ea55a130e1 |