Project Tree Generator

A versatile Python script to generate a tree-like representation of any directory structure, with support for exclusion patterns defined in both .gitignore and .treeignore files. Perfect for documenting project structures, visualizing directories, and sharing insights about your codebase.

Table of Contents

• Features
• Demo
• Installation
• Usage
  • Basic Usage
  • Advanced Options
• Examples
• Customization
• Troubleshooting
• Contributing
• License

Features

• Recursive Directory Traversal: Explore all subdirectories and files from any root directory.
• Exclusion Support: Utilize both .gitignore and .treeignore files to exclude specific files and folders.
• Default Exclusions: Automatically excludes common directories like .git/, __pycache__/, and others.
• Color-Coded Output: Differentiate between directories, Python packages, files, and symbolic links with colors for enhanced readability when outputting to the console.
• Output to File: Save the generated tree structure to a text file without ANSI color codes.
• Symbolic Link Handling: Detect and display symbolic links, preventing infinite loops.
• Cross-Platform Compatibility: Works seamlessly on Windows, macOS, and Linux.

Example output of the Directory Tree Generator.

Installation

Prerequisites

• Python 3.6 or higher must be installed on your system. You can download it from the official website.

Clone the Repository

git clone https://github.com/yourusername/directory-tree-generator.git
cd directory-tree-generator

Install Dependencies

It's recommended to use a virtual environment to manage dependencies.

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Alternatively, install the required packages directly:

pip install pathspec colorama

Usage

The get_tree.py script can be run from any directory to visualize its structure.

Basic Usage

Navigate to the directory you want to visualize and run the script:

python get_tree.py

This will print the directory tree to the console, excluding the .git directory and any patterns specified in .gitignore and .treeignore files in the root directory.

Advanced Options

usage: get_tree.py [-h] [-o OUTPUT] [directory]

Generate a tree-like structure of a directory with exclusion support using .treeignore and .gitignore.

positional arguments:
  directory             The root directory to generate the tree from. Defaults to the current directory.

optional arguments:
  -h, --help            show this help message and exit
  -o OUTPUT, --output OUTPUT
                        Path to a file to save the tree structure. If not provided, it will be printed to the console.

Examples

• Generate Tree for Current Directory:

  python get_tree.py

• Specify a Different Root Directory:

  python get_tree.py /path/to/your/project

• Save Output to a File:

  python get_tree.py -o tree_structure.txt

• Combine Options:

  python get_tree.py /path/to/your/project -o project_tree.txt

Examples

Basic Output

Loaded exclusion patterns from '/home/user/example_project/.treeignore'.
Loaded exclusion patterns from '/home/user/example_project/.gitignore'.
Exclusion patterns loaded from '.treeignore' and '.gitignore'.
example_project/
├── src/
│   ├── main.py
│   ├── utils.py
│   └── modules/
│       ├── module1.py
│       └── module2.py
├── tests/
│   ├── test_main.py
│   └── test_utils.py
├── .gitignore
├── README.md
└── requirements.txt

Note: The .git/ directory and any files or directories matching patterns in .treeignore and .gitignore are excluded from the output.

Output Saved to File

After running:

python get_tree.py -o tree_structure.txt

Content of tree_structure.txt:

example_project/
├── src/
│   ├── main.py
│   ├── utils.py
│   └── modules/
│       ├── module1.py
│       └── module2.py
├── tests/
│   ├── test_main.py
│   └── test_utils.py
├── .gitignore
├── README.md
└── requirements.txt

Customization

Creating and Customizing .treeignore

To exclude specific files and directories from the tree output, define your exclusion patterns in a .treeignore file located in the root directory of your project.

Example .treeignore File:

# Additional exclusions
build/
dist/
*.env

Adding Custom Patterns:

Feel free to add or remove patterns based on your project's requirements. For instance, if you use a different virtual environment directory or have other directories you wish to exclude, simply add them to the .treeignore file.

Handling Nested .treeignore Files

Currently, the script only recognizes a single .treeignore file in the root directory. If you have nested directories that require their own exclusion patterns, you can:

1. Manually Add Patterns: Extend your root .treeignore to include nested patterns.

   Example:

   # Exclude specific nested directories
   nested_dir/.cache/
   nested_dir/temp/

2. Modify the Script: Enhance the script to detect and load multiple .treeignore files within subdirectories. This requires more complex logic and is beyond the current scope but can be implemented as an advanced feature.

Color-Coding Enhancements

The script uses the colorama library to color-code different elements for better readability:

• Blue (Fore.BLUE) for directories
• Green (Fore.GREEN) for Python packages
• Yellow (Fore.YELLOW) for files
• Cyan (Fore.CYAN) for symbolic links

Feel free to customize these colors in the get_tree.py script to suit your preferences.

Troubleshooting

If you encounter any issues or have questions, please check the Issues section of the GitHub repository. For additional help, you can open a new issue with a detailed description of the problem.

Contributing

Contributions are welcome! If you would like to contribute to the project, please follow these steps:

1. Fork the repository.
2. Create a new branch for your changes.
3. Make your changes and test thoroughly.
4. Submit a pull request with a clear description of your changes.

License

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

---

Feel free to adjust any part of this to better fit your needs!

Developed with ❤️ by Ivan Manko