cpdirmk

cpdirmk is a powerful command-line tool that generates a Markdown representation of directory structures, including the content of text files. It's perfect for documentation, project overviews, and sharing folder structures in a readable format.

Features

• 📁 Generates a Markdown representation of directory structures
• 📄 Includes content of text files in the output
• 🌳 Supports customizable depth limitation for directory traversal
• 🚫 Allows ignoring specific files or directories
• 🔍 Intelligently identifies and handles various file types
• 🔄 Supports .gitignore files to automatically exclude ignored files
• 💻 Compatible with Linux, macOS, and Windows (via MSYS/Cygwin)
• 🎨 Produces clean and formatted Markdown output

Table of Contents

• cpdirmk
  • Features
  • Table of Contents
  • Installation
    • Linux and macOS
    • Windows
  • Usage
  • Options
  • Examples
  • File Type Handling
  • Compatibility
  • Contributing
  • License
  • Author
  • Acknowledgments

Installation

Linux and macOS

1. Clone this repository:

   git clone https://github.com/ericbercol/cpdirmk.git
   

2. Navigate to the project directory:

   cd cpdirmk
   

3. Run the installation script with root privileges:

   sudo ./install.sh
   

   The script will install cpdirmk and its man page, making it available system-wide.

Windows

1. Install MSYS2 or Cygwin on your Windows system.

2. Clone this repository:

   git clone https://github.com/ericbercol/cpdirmk.git
   

3. Navigate to the project directory:

   cd cpdirmk
   

4. Run the installation script:

   ./install.sh
   

   The script will install cpdirmk in the user's bin directory.

Usage

Basic syntax:

cpdirmk [OPTIONS] DIRECTORY

Options

• --help: Display the help message and exit
• --version: Show the program version and exit
• --output=FILE: Specify the output file (default: output to terminal)
• --depth=NUMBER: Set the maximum depth for directory traversal
• --ignore=PATTERN: Ignore files/directories matching the specified pattern
• --use-gitignore: Respect patterns in .gitignore files found in directories
• --max-file-size=SIZE: Set the maximum size (in bytes) to include file content

Examples

1. Generate a Markdown representation of the current directory:

   cpdirmk .
   

2. Create a structure of a specific directory with a custom output file:

   cpdirmk --output project_structure.md /path/to/your/project
   

3. Limit the depth and ignore certain files/directories:

   cpdirmk --depth 3 --ignore '*.tmp' --ignore 'node_modules' --output limited_structure.md /path/to/project
   

4. Use .gitignore patterns to exclude files ignored by git:

   cpdirmk --use-gitignore --output project_structure.md /path/to/project
   

File Type Handling

cpdirmk intelligently handles various file types:

• Text Files: Content is included in the Markdown output.
• Binary Files: Marked as binary without content display.
• Special Files: Identified and handled appropriately (e.g., executables, symlinks).
• Large Files: Size is displayed instead of content for files exceeding a certain threshold.

Compatibility

cpdirmk has been tested and works on the following platforms:

• Linux: All major distributions
• macOS: Versions 10.13 and higher
• Windows: Via MSYS2 or Cygwin

Contributing

Contributions to cpdirmk are welcome! Here's how you can help:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Make your changes and commit them with clear, descriptive messages.
4. Push your changes to your fork.
5. Submit a pull request with a clear description of your changes.

Please ensure your code adheres to the existing style and passes all tests.

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Author

Eric Coleta - ericbercol@gmail.com

Acknowledgments

• Thanks to all contributors who have helped shape cpdirmk.
• Inspired by the need for easy-to-share directory structures in Markdown format.

---

For more detailed information, please refer to the man page by running man cpdirmk after installation or cpdirmk --help.