• 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

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

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.

• 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

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

1. Download the script:

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

2. Make the script executable:

   chmod +x dirdoc.sh
   

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

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

• -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

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
   

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

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.

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.

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.

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.

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!