gopeek

README

GoPeek

GoPeek is a lightweight command-line tool that generates comprehensive documentation of project structures. It recursively scans directories to create a navigable Markdown document containing both the project tree and file contents, making it ideal for project exploration, documentation and AI context providing.

Features

• 🌳 Recursive directory scanning with an intuitive tree structure
• 📝 Automatic Markdown generation with file contents
• 🔍 Smart binary file detection
• ⚡ Efficient large file handling with size limits
• 🎯 Configurable ignore patterns (supports .gitignore)
• 🔗 Generated anchors for easy navigation

Installation

go install github.com/nouuu/gopeek/cmd/gopeek@latest

Or build from source:

git clone https://github.com/nouuu/gopeek.git
cd gopeek
make build

You can also install it from source :

git clone https://github.com/nouuu/gopeek.git
cd gopeek
make install

Usage

Basic usage:

gopeek [path] [flags]

Available flags:

Flags:
  -o, --output string        Output file path (default "project_knowledge.md")
  -i, --ignore stringSlice   Patterns to ignore
  -v, --version              Show version
  --verbose                  Enable verbose output

Example:

# Scan current directory
gopeek .

# Scan specific directory with custom output
gopeek /path/to/project -o documentation.md

# Scan with custom ignore patterns
gopeek . -i "*.log" -i "build/*"

Output Format

GoPeek generates a structured Markdown document with two main sections:

1. Project Structure: A tree view of your project with clickable links
2. File Contents: The content of each file with syntax highlighting

Example output:

# Project Structure
- 📁 project
  - 📄 [main.go](#main-go)
  - 📁 internal
    - 📄 [types.go](#internal-types-go)

# Files Content
# 📄 main.go
```go
package main
// ... file content

Development

Prerequisites

• Go 1.22 or higher
• Make (for build automation)

Building

make build

Testing

make test

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Roadmap 🗺️

Core Features ✨

• Basic directory scanning
• Markdown output generation
• Binary file detection
• .gitignore support
• CLI interface with cobra
• File size limits
• Github Actions CI/CD

Next Steps 🚀

• Advanced Error Handling 🛡️
  • Custom error types
  • Error context and wrapping
  • Operation summaries
• Extended Output Options 📝
  • HTML with navigation
  • JSON output
  • Template customization
• Performance Features ⚡
  • Parallel file scanning
  • Memory usage optimization
  • Progress indicators

Acknowledgments

• Inspired by the need for better project documentation tools
• Built with Cobra