mvn-tree-visualizer


Namemvn-tree-visualizer JSON
Version 1.6.0 PyPI version JSON
download
home_pageNone
SummaryA simple command line tool to visualize the dependency tree of a Maven project in a graphical format.
upload_time2025-07-24 16:48:26
maintainerNone
docs_urlNone
authorNone
requires_python>=3.13
licenseNone
keywords cli command-line dependency graph maven mermaid tool tree visualization
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Maven Dependency Tree Visualizer

[![PyPI version](https://badge.fury.io/py/mvn-tree-visualizer.svg)](https://badge.fury.io/py/mvn-tree-visualizer)
![Python](https://img.shields.io/badge/python-3.13+-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
[![Downloads](https://pepy.tech/badge/mvn-tree-visualizer)](https://pepy.tech/project/mvn-tree-visualizer)
[![CI](https://github.com/dyka3773/mvn-tree-visualizer/workflows/CI/badge.svg)](https://github.com/dyka3773/mvn-tree-visualizer/actions)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

A simple command-line tool to visualize the dependency tree of a Maven project in a graphical and interactive format.

This tool was born out of the frustration of not being able to easily visualize the dependency tree of a Maven project. The `mvn dependency:tree` command is great, but the output can be hard to read, especially for large projects. This tool aims to solve that problem by providing a simple way to generate an interactive diagram or a structured JSON output of the dependency tree.

## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [How to Use](#how-to-use)
- [Examples](#examples)
- [Options](#options)
- [Performance](#performance)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)

## Installation

Install the package from PyPI:

```bash
pip install mvn-tree-visualizer
```

## Features

- **🌐 Multiple Output Formats:**
  - **HTML:** Generates an interactive HTML diagram of your dependency tree using Mermaid.js.
  - **JSON:** Creates a structured JSON representation of the dependency tree, perfect for scripting or integration with other tools.
- **🎨 Theme System:** Choose from 2 built-in themes (minimal, dark) for clean and consistent diagram styling.
- **🔄 Watch Mode:** Automatically regenerates diagrams when Maven dependency files change using the `--watch` flag.
- **📋 Version Display:** Toggle dependency versions in outputs with `--show-versions`
- **💾 Enhanced Downloads:** SVG and PNG export directly from browser
- **📂 Smart File Handling:** Automatically finds and merges multiple `maven_dependency_file` files from different subdirectories.
- **🎯 Color Coding:** Visual distinction between root, intermediate, and leaf dependencies

## How to Use

### Step 1: Generate the dependency file

Run the following command in your terminal at the root of your Maven project. This will generate a file named `maven_dependency_file` in each module's `target` directory.

```bash
mvn dependency:tree -DoutputFile=maven_dependency_file -DappendOutput=true
```

> **💡 Tip:** You can add other options like `-Dincludes="org.example"` to filter the dependencies.

### Step 2: Visualize the dependency tree

Use the `mvn-tree-visualizer` command to generate the diagram.

#### HTML Output (Interactive Diagram)
```bash
mvn-tree-visualizer --filename "maven_dependency_file" --output "diagram.html" --format html
```

#### JSON Output (Structured Data)
```bash
mvn-tree-visualizer --filename "maven_dependency_file" --output "dependencies.json" --format json
```

#### With Version Information
```bash
mvn-tree-visualizer --filename "maven_dependency_file" --output "diagram.html" --show-versions
```

#### With Custom Themes
```bash
# Dark theme for low-light environments  
mvn-tree-visualizer --filename "maven_dependency_file" --output "diagram.html" --theme dark

# Default minimal theme (clean monospace design)
mvn-tree-visualizer --filename "maven_dependency_file" --output "diagram.html"
```

#### JSON Output with Versions
```bash
mvn-tree-visualizer --filename "maven_dependency_file" --output "dependencies.json" --format json --show-versions
```

#### Watch Mode (Auto-regeneration)
```bash
mvn-tree-visualizer --filename "maven_dependency_file" --output "diagram.html" --watch
```

> **💡 Tip:** In watch mode, the tool will monitor for changes to your Maven dependency files and automatically regenerate the diagram. Perfect for development workflows! Press `Ctrl+C` to stop watching.

### Step 3: View the output

- **HTML:** Open the generated `diagram.html` file in your web browser to view the interactive dependency tree.
- **JSON:** Use the `dependencies.json` file in your scripts or other tools.

## Examples

Check out the [`examples/`](examples/) directory for sample Maven dependency files and their outputs:

- **Simple Project**: Basic Spring Boot application with common dependencies
- **Complex Project**: Realistic microservice with comprehensive dependencies

Each example includes:
- Sample Maven dependency tree file
- Generated HTML and JSON outputs
- Usage instructions

## Options

| Option | Description | Default |
|--------|-------------|---------|
| `--filename` | The name of the file containing the Maven dependency tree | `maven_dependency_file` |
| `--output` | The name of the output file | `diagram.html` |
| `--format` | The output format (`html` or `json`) | `html` |
| `--theme` | Theme for HTML diagrams (`minimal`, `dark`) | `minimal` |
| `--show-versions` | Show dependency versions in the diagram | `False` |
| `--watch` | Watch for file changes and auto-regenerate diagram | `False` |
| `--directory` | The directory to scan for the Maven dependency file(s) | current directory |
| `--keep-tree` | Keep the intermediate `dependency_tree.txt` file | `False` |
| `--help` | Show the help message and exit | - |

### Theme Options

- **`minimal`**: Clean monospace design with simple black borders (default)
- **`dark`**: Same minimal styling but with white text on black background

📖 **See the complete [Theme Documentation](docs/THEMES.md) for detailed information about themes and interactive features.**

## Performance

**For Large Projects:**
- Consider filtering dependencies at the Maven level using `-Dincludes` or `-Dexcludes` parameters
- The tool can handle projects with hundreds of dependencies efficiently

**Memory Usage:**
- Memory usage scales with the number of dependencies
- Typical projects (50-200 dependencies) use minimal memory
- Very large projects (1000+ dependencies) may require more memory

## Troubleshooting

### Common Issues

**"No dependency files found"**
- The tool now provides detailed guidance including:
  - Exact directory searched and filename expected
  - Maven commands to generate dependency files
  - Instructions to ensure you're in a directory with pom.xml

**"Empty or invalid output"**
- Enhanced error messages now include:
  - Specific error details (encoding, permissions, empty files)
  - Validation of file content and format
  - Suggestions for fixing common parsing issues

**"Browser doesn't display the diagram"**
- Ensure you're opening the HTML file in a modern browser
- Check browser console for JavaScript errors
- Try a different browser (Chrome, Firefox, Safari)

**"Permission denied errors"**
- Improved diagnostics for:
  - Directory read/write permissions
  - File access issues
  - Output directory creation problems

### Getting Help

- Check the [examples](examples/) directory for working samples
- Review the [issues](https://github.com/dyka3773/mvn-tree-visualizer/issues) page
- Create a new issue with your Maven dependency file sample

## Contributing

Contributions are welcome! If you have any ideas, suggestions, or bug reports, please open an issue or submit a pull request.

Please read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "mvn-tree-visualizer",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.13",
    "maintainer_email": null,
    "keywords": "cli, command-line, dependency, graph, maven, mermaid, tool, tree, visualization",
    "author": null,
    "author_email": "Iraklis Konsoulas <dyka3773@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/71/aa/901889b49c09e950efd9b014be996a37361a2589c286ffd528234de51a14/mvn_tree_visualizer-1.6.0.tar.gz",
    "platform": null,
    "description": "# Maven Dependency Tree Visualizer\n\n[![PyPI version](https://badge.fury.io/py/mvn-tree-visualizer.svg)](https://badge.fury.io/py/mvn-tree-visualizer)\n![Python](https://img.shields.io/badge/python-3.13+-blue.svg)\n![License](https://img.shields.io/badge/license-MIT-green.svg)\n[![Downloads](https://pepy.tech/badge/mvn-tree-visualizer)](https://pepy.tech/project/mvn-tree-visualizer)\n[![CI](https://github.com/dyka3773/mvn-tree-visualizer/workflows/CI/badge.svg)](https://github.com/dyka3773/mvn-tree-visualizer/actions)\n[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n\nA simple command-line tool to visualize the dependency tree of a Maven project in a graphical and interactive format.\n\nThis tool was born out of the frustration of not being able to easily visualize the dependency tree of a Maven project. The `mvn dependency:tree` command is great, but the output can be hard to read, especially for large projects. This tool aims to solve that problem by providing a simple way to generate an interactive diagram or a structured JSON output of the dependency tree.\n\n## Table of Contents\n- [Features](#features)\n- [Installation](#installation)\n- [How to Use](#how-to-use)\n- [Examples](#examples)\n- [Options](#options)\n- [Performance](#performance)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Installation\n\nInstall the package from PyPI:\n\n```bash\npip install mvn-tree-visualizer\n```\n\n## Features\n\n- **\ud83c\udf10 Multiple Output Formats:**\n  - **HTML:** Generates an interactive HTML diagram of your dependency tree using Mermaid.js.\n  - **JSON:** Creates a structured JSON representation of the dependency tree, perfect for scripting or integration with other tools.\n- **\ud83c\udfa8 Theme System:** Choose from 2 built-in themes (minimal, dark) for clean and consistent diagram styling.\n- **\ud83d\udd04 Watch Mode:** Automatically regenerates diagrams when Maven dependency files change using the `--watch` flag.\n- **\ud83d\udccb Version Display:** Toggle dependency versions in outputs with `--show-versions`\n- **\ud83d\udcbe Enhanced Downloads:** SVG and PNG export directly from browser\n- **\ud83d\udcc2 Smart File Handling:** Automatically finds and merges multiple `maven_dependency_file` files from different subdirectories.\n- **\ud83c\udfaf Color Coding:** Visual distinction between root, intermediate, and leaf dependencies\n\n## How to Use\n\n### Step 1: Generate the dependency file\n\nRun the following command in your terminal at the root of your Maven project. This will generate a file named `maven_dependency_file` in each module's `target` directory.\n\n```bash\nmvn dependency:tree -DoutputFile=maven_dependency_file -DappendOutput=true\n```\n\n> **\ud83d\udca1 Tip:** You can add other options like `-Dincludes=\"org.example\"` to filter the dependencies.\n\n### Step 2: Visualize the dependency tree\n\nUse the `mvn-tree-visualizer` command to generate the diagram.\n\n#### HTML Output (Interactive Diagram)\n```bash\nmvn-tree-visualizer --filename \"maven_dependency_file\" --output \"diagram.html\" --format html\n```\n\n#### JSON Output (Structured Data)\n```bash\nmvn-tree-visualizer --filename \"maven_dependency_file\" --output \"dependencies.json\" --format json\n```\n\n#### With Version Information\n```bash\nmvn-tree-visualizer --filename \"maven_dependency_file\" --output \"diagram.html\" --show-versions\n```\n\n#### With Custom Themes\n```bash\n# Dark theme for low-light environments  \nmvn-tree-visualizer --filename \"maven_dependency_file\" --output \"diagram.html\" --theme dark\n\n# Default minimal theme (clean monospace design)\nmvn-tree-visualizer --filename \"maven_dependency_file\" --output \"diagram.html\"\n```\n\n#### JSON Output with Versions\n```bash\nmvn-tree-visualizer --filename \"maven_dependency_file\" --output \"dependencies.json\" --format json --show-versions\n```\n\n#### Watch Mode (Auto-regeneration)\n```bash\nmvn-tree-visualizer --filename \"maven_dependency_file\" --output \"diagram.html\" --watch\n```\n\n> **\ud83d\udca1 Tip:** In watch mode, the tool will monitor for changes to your Maven dependency files and automatically regenerate the diagram. Perfect for development workflows! Press `Ctrl+C` to stop watching.\n\n### Step 3: View the output\n\n- **HTML:** Open the generated `diagram.html` file in your web browser to view the interactive dependency tree.\n- **JSON:** Use the `dependencies.json` file in your scripts or other tools.\n\n## Examples\n\nCheck out the [`examples/`](examples/) directory for sample Maven dependency files and their outputs:\n\n- **Simple Project**: Basic Spring Boot application with common dependencies\n- **Complex Project**: Realistic microservice with comprehensive dependencies\n\nEach example includes:\n- Sample Maven dependency tree file\n- Generated HTML and JSON outputs\n- Usage instructions\n\n## Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--filename` | The name of the file containing the Maven dependency tree | `maven_dependency_file` |\n| `--output` | The name of the output file | `diagram.html` |\n| `--format` | The output format (`html` or `json`) | `html` |\n| `--theme` | Theme for HTML diagrams (`minimal`, `dark`) | `minimal` |\n| `--show-versions` | Show dependency versions in the diagram | `False` |\n| `--watch` | Watch for file changes and auto-regenerate diagram | `False` |\n| `--directory` | The directory to scan for the Maven dependency file(s) | current directory |\n| `--keep-tree` | Keep the intermediate `dependency_tree.txt` file | `False` |\n| `--help` | Show the help message and exit | - |\n\n### Theme Options\n\n- **`minimal`**: Clean monospace design with simple black borders (default)\n- **`dark`**: Same minimal styling but with white text on black background\n\n\ud83d\udcd6 **See the complete [Theme Documentation](docs/THEMES.md) for detailed information about themes and interactive features.**\n\n## Performance\n\n**For Large Projects:**\n- Consider filtering dependencies at the Maven level using `-Dincludes` or `-Dexcludes` parameters\n- The tool can handle projects with hundreds of dependencies efficiently\n\n**Memory Usage:**\n- Memory usage scales with the number of dependencies\n- Typical projects (50-200 dependencies) use minimal memory\n- Very large projects (1000+ dependencies) may require more memory\n\n## Troubleshooting\n\n### Common Issues\n\n**\"No dependency files found\"**\n- The tool now provides detailed guidance including:\n  - Exact directory searched and filename expected\n  - Maven commands to generate dependency files\n  - Instructions to ensure you're in a directory with pom.xml\n\n**\"Empty or invalid output\"**\n- Enhanced error messages now include:\n  - Specific error details (encoding, permissions, empty files)\n  - Validation of file content and format\n  - Suggestions for fixing common parsing issues\n\n**\"Browser doesn't display the diagram\"**\n- Ensure you're opening the HTML file in a modern browser\n- Check browser console for JavaScript errors\n- Try a different browser (Chrome, Firefox, Safari)\n\n**\"Permission denied errors\"**\n- Improved diagnostics for:\n  - Directory read/write permissions\n  - File access issues\n  - Output directory creation problems\n\n### Getting Help\n\n- Check the [examples](examples/) directory for working samples\n- Review the [issues](https://github.com/dyka3773/mvn-tree-visualizer/issues) page\n- Create a new issue with your Maven dependency file sample\n\n## Contributing\n\nContributions are welcome! If you have any ideas, suggestions, or bug reports, please open an issue or submit a pull request.\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "A simple command line tool to visualize the dependency tree of a Maven project in a graphical format.",
    "version": "1.6.0",
    "project_urls": {
        "source": "https://github.com/dyka3773/mvn-tree-visualizer"
    },
    "split_keywords": [
        "cli",
        " command-line",
        " dependency",
        " graph",
        " maven",
        " mermaid",
        " tool",
        " tree",
        " visualization"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "8079e6f893dfd2a750fa4c3fa9c2c350910191cd9b26ecc62bcea60efa50ad75",
                "md5": "f96834a17e4dba76776a7888b5b941a9",
                "sha256": "00fae42d7f2a30a6bb2f03068630ad7a927e35aab009bf4342ac61b36caa5d7a"
            },
            "downloads": -1,
            "filename": "mvn_tree_visualizer-1.6.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "f96834a17e4dba76776a7888b5b941a9",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.13",
            "size": 19598,
            "upload_time": "2025-07-24T16:48:25",
            "upload_time_iso_8601": "2025-07-24T16:48:25.866836Z",
            "url": "https://files.pythonhosted.org/packages/80/79/e6f893dfd2a750fa4c3fa9c2c350910191cd9b26ecc62bcea60efa50ad75/mvn_tree_visualizer-1.6.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "71aa901889b49c09e950efd9b014be996a37361a2589c286ffd528234de51a14",
                "md5": "5876625394974c60c04ae9969680b9ea",
                "sha256": "7532edf6d0c2ee3a6916b8a78247cc05836f7c8c8b71e343c104cbd52573977c"
            },
            "downloads": -1,
            "filename": "mvn_tree_visualizer-1.6.0.tar.gz",
            "has_sig": false,
            "md5_digest": "5876625394974c60c04ae9969680b9ea",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.13",
            "size": 85372,
            "upload_time": "2025-07-24T16:48:26",
            "upload_time_iso_8601": "2025-07-24T16:48:26.625896Z",
            "url": "https://files.pythonhosted.org/packages/71/aa/901889b49c09e950efd9b014be996a37361a2589c286ffd528234de51a14/mvn_tree_visualizer-1.6.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-24 16:48:26",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "dyka3773",
    "github_project": "mvn-tree-visualizer",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "mvn-tree-visualizer"
}
        
Elapsed time: 2.08575s