DirDoc: Directory Documentation Generator

Table of Contents

• DirDoc: Directory Documentation Generator
  • Table of Contents
  • Introduction
  • Quick Start
  • Features
  • Requirements
  • Installation
  • Usage
    • Basic Usage
    • Options
    • Examples
  • Code Walkthrough
  • Customization
  • Troubleshooting
  • Contributing
  • FAQ
  • License

Introduction

DirDoc is a powerful and flexible Bash script designed to create a comprehensive markdown file containing the contents of all text files within a specified directory. It also provides a visual representation of the directory structure, making it an invaluable tool for documentation and code review processes.

This script is particularly useful for:

• Generating documentation for software projects
• Creating snapshots of directory contents for archival purposes
• Facilitating code reviews by providing an easy-to-navigate markdown file of the entire project

Quick Start

1. Download the script:

   curl -O https://raw.githubusercontent.com/cansakirt/DirDoc/main/dirdoc.sh
   

2. Make it executable:

   chmod +x dirdoc.sh
   

3. Run it on a directory:

   ./dirdoc.sh /path/to/your/directory
   

4. Find the generated markdown file in your current directory.

Features

• Generates a markdown file with contents of all text files in a directory
• Creates a visual tree-like representation of the directory structure
• Allows exclusion of files based on patterns
• Supports limiting the depth of directory traversal
• Provides debug output for troubleshooting
• Utilizes parallel processing for improved performance on multi-core systems
• Customizable output file naming

Requirements

• Bash shell (version 4.0 or later recommended)
• Standard Unix utilities: find, grep, xargs, file, date, nproc

Installation

1. Download the script:

   curl -O https://raw.githubusercontent.com/cansakirt/DirDoc/main/dirdoc.sh
   

2. Make the script executable:

   chmod +x dirdoc.sh
   

Usage

Basic Usage

./dirdoc.sh /path/to/your/directory

This will generate a markdown file named your-directory_YYYYMMDD_HHMMSS.md in the current working directory.

Options

• -o, --output FILE: Specify the output file name
• -e, --exclude PATTERN: Exclude files matching the given pattern (can be used multiple times)
• -d, --debug: Enable debug output
• -m, --max-depth DEPTH: Maximum depth to recurse (default: unlimited)
• -h, --help: Display help message and exit

Examples

1. Basic usage:

   ./dirdoc.sh /path/to/your/directory
   

2. Specify output file:

   ./dirdoc.sh -o project_docs.md /path/to/your/directory
   

3. Exclude all .log files:

   ./dirdoc.sh -e "*.log" /path/to/your/directory
   

4. Exclude multiple file types (log and tmp):

   ./dirdoc.sh -e "*.log" -e "*.tmp" /path/to/your/directory
   

5. Limit directory traversal to 3 levels:

   ./dirdoc.sh -m 3 /path/to/your/directory
   

6. Exclude hidden files and directories:

   ./dirdoc.sh -e "*/.*" /path/to/your/directory
   

7. Exclude specific directory:

   ./dirdoc.sh -e "*/node_modules/*" /path/to/your/directory
   

8. Combine multiple options:

   ./dirdoc.sh -o project_docs.md -e "*.log" -e "*/.*" -m 3 -d /path/to/your/directory
   

Code Walkthrough

For a detailed walkthrough of the script's main components, please refer to the comments within the dirdoc.sh file.

Customization

You can customize the script by modifying the following aspects:

• Change the default timestamp format in the TIMESTAMP variable.
• Modify the create_tree function to alter the tree representation.
• Adjust the process_file function to change how file contents are formatted in the markdown output.

Troubleshooting

1. Script not running:

   • Ensure the script has execute permissions: chmod +x dirdoc.sh

2. Files not being processed:

   • Check if the files are readable by the user running the script.
   • Verify that the files are recognized as text files by the file command.

3. Slow performance:

   • For large directories, try using the -m option to limit the depth of traversal.
   • Ensure your system has multiple CPU cores to benefit from parallel processing.

4. Unexpected exclusions:

   • Use the -d option to enable debug output and see which files are being processed or excluded.

Contributing

Contributions to improve the script are welcome! Please follow these steps:

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 and create a pull request.

For more details, please see the CONTRIBUTING.md file.

FAQ

Q: Can DirDoc handle large directories with many files?

A: Yes, DirDoc uses parallel processing to handle large directories efficiently. However, for extremely large directories, you may want to use the -m option to limit the depth of traversal.

Q: Is it possible to exclude certain file types or directories?

A: Absolutely! You can use the -e option to exclude files or directories based on patterns. For example, -e "*.log" will exclude all .log files.

Q: Can I customize the output format?

A: The current version outputs in Markdown format. If you need a different format, you can modify the process_file function in the script. We're considering adding more output formats in future versions.

Q: Does DirDoc work on Windows?

A: DirDoc is designed for Unix-like systems. It may work on Windows using WSL (Windows Subsystem for Linux) or Git Bash, but it's not officially supported on Windows.

Q: How can I contribute to DirDoc?

A: We welcome contributions! Please see our CONTRIBUTING.md file for guidelines on how to contribute.

License

This script is released under the MIT License. See the LICENSE file for details.

---

We hope DirDoc enhances your documentation and code review processes. If you have any questions or suggestions, please open an issue in the repository. Happy documenting!