{"id":20731546,"url":"https://github.com/datumbrain/dirtree","last_synced_at":"2026-03-05T06:05:46.672Z","repository":{"id":253000414,"uuid":"842154630","full_name":"datumbrain/dirtree","owner":"datumbrain","description":"A utility to print directory tree respecting repo's ignore file.","archived":false,"fork":false,"pushed_at":"2024-08-23T06:59:39.000Z","size":9,"stargazers_count":2,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-23T22:05:48.398Z","etag":null,"topics":["go","golang","shell","tree","tree-structure","utility"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/datumbrain.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-13T19:30:01.000Z","updated_at":"2025-03-05T04:04:28.000Z","dependencies_parsed_at":"2024-08-13T22:48:37.450Z","dependency_job_id":"39cb83c0-c587-4c2b-a0ce-af1f9411e8b8","html_url":"https://github.com/datumbrain/dirtree","commit_stats":null,"previous_names":["datumbrain/dirtree"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datumbrain%2Fdirtree","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datumbrain%2Fdirtree/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datumbrain%2Fdirtree/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datumbrain%2Fdirtree/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datumbrain","download_url":"https://codeload.github.com/datumbrain/dirtree/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250522300,"owners_count":21444511,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","golang","shell","tree","tree-structure","utility"],"created_at":"2024-11-17T05:15:46.381Z","updated_at":"2026-03-05T06:05:46.664Z","avatar_url":"https://github.com/datumbrain.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dirtree\n\n[![CI](https://github.com/datumbrain/dirtree/actions/workflows/ci.yml/badge.svg)](https://github.com/datumbrain/dirtree/actions/workflows/ci.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/datumbrain/dirtree)](https://goreportcard.com/report/github.com/datumbrain/dirtree)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA lightweight command-line utility that displays directory tree structures while intelligently respecting `.gitignore` patterns. Perfect for documenting project structures, exploring codebases, and generating clean directory listings.\n\n## Features\n\n- **Multiple Output Formats**: Text (traditional), JSON (machine-readable), and Markdown (LLM-optimized)\n- **LLM-Optimized Mode**: Special `--llm` flag for AI agent consumption with sensible defaults\n- **Gitignore-Aware**: Automatically respects `.gitignore` files at all directory levels\n- **Hierarchical Patterns**: Inherits and combines gitignore rules from parent directories\n- **Smart Sorting**: Organizes output with directories first, then files, then dotfiles (all alphabetically sorted)\n- **Colorized Output**: Beautiful ANSI colors for directories, files, and file types with auto-detection\n- **Depth Limiting**: Control how deep to traverse with `-L` flag\n- **File Count Limiting**: Limit total files displayed with `--max-files` flag\n- **Clean Output**: Uses ASCII tree characters (├──, └──, │) for clear visual hierarchy\n- **Fast \u0026 Lightweight**: Single binary with minimal dependencies\n- **Cross-Platform**: Works on Linux, macOS, and Windows\n\n## Installation\n\n### Using Go Install (Recommended)\n\n```bash\ngo install github.com/datumbrain/dirtree@latest\n```\n\n### Build from Source\n\n```bash\ngit clone https://github.com/datumbrain/dirtree.git\ncd dirtree\ngo build\n```\n\n## Usage\n\n### Basic Usage\n\nDisplay the tree structure of the current directory:\n\n```bash\ndirtree\n```\n\n### Command-Line Options\n\n```bash\ndirtree [options] [directory]\n\nOptions:\n  -L int\n        Maximum depth of directory tree (0 = unlimited)\n  -level int\n        Maximum depth of directory tree (0 = unlimited)\n  -color string\n        Colorize output: auto, always, never (default \"auto\")\n  -format string\n        Output format: text, json, markdown (or md) (default \"text\")\n  -o string\n        Output format: text, json, markdown (or md) (default \"text\")\n  -max-files int\n        Maximum number of files to display (0 = unlimited)\n  -llm\n        LLM-optimized output (equivalent to: --format markdown --level 3 --max-files 200)\n```\n\n### Examples\n\n**Specify a directory:**\n```bash\ndirtree /path/to/directory\n```\n\n**Limit depth to 2 levels:**\n```bash\ndirtree -L 2\n```\n\n**Show only top-level items:**\n```bash\ndirtree --level 1\n```\n\n**Force colored output:**\n```bash\ndirtree --color always\n```\n\n**Disable colors:**\n```bash\ndirtree --color never\n```\n\n**Combine options:**\n```bash\ndirtree --color always -L 3 /path/to/directory\n```\n\n**Respect NO_COLOR environment variable:**\n```bash\nNO_COLOR=1 dirtree\n```\n\n**JSON output for programmatic use:**\n```bash\ndirtree --format json\n# or using the short flag\ndirtree -o json\n```\n\n**Markdown output for documentation:**\n```bash\ndirtree --format markdown\n# or using the alias\ndirtree -o md\n```\n\n**LLM-optimized mode (markdown, depth 3, max 200 files):**\n```bash\ndirtree --llm\n```\n\n**Limit number of files displayed:**\n```bash\ndirtree --max-files 50\n```\n\n**Combine format with other options:**\n```bash\ndirtree --format json -L 2 --max-files 100\n```\n\n### Example Output\n\n**Without colors:**\n```\n.\n├── cmd\n│   └── main.go\n├── internal\n│   ├── config.go\n│   └── utils.go\n├── pkg\n│   └── api\n│       └── handler.go\n├── go.mod\n├── go.sum\n├── README.md\n└── .gitignore\n```\n\n**With colors** (uses different colors for directories, files, and file types):\n- Directories appear in **blue and bold**\n- Regular files appear in white\n- Dotfiles appear in gray\n- Markdown/documentation files appear in cyan\n- Image files appear in magenta\n- Executable files appear in green and bold\n\n## Output Formats\n\ndirtree supports three output formats to suit different use cases:\n\n### Text Format (Default)\n\nTraditional tree output with ASCII art. Perfect for terminal display and human reading.\n\n```bash\ndirtree --format text\n```\n\nOutput:\n```\n.\n├── cmd\n│   └── main.go\n├── pkg\n│   └── api\n│       └── handler.go\n├── README.md\n└── go.mod\n```\n\n### JSON Format\n\nMachine-readable format ideal for programmatic processing and integration with other tools.\n\n```bash\ndirtree --format json\n```\n\nOutput:\n```json\n{\n  \"root\": \".\",\n  \"depth\": 0,\n  \"stats\": {\n    \"files\": 3,\n    \"dirs\": 3\n  },\n  \"nodes\": [\n    {\"path\": \"cmd\", \"type\": \"dir\"},\n    {\"path\": \"cmd/main.go\", \"type\": \"file\"},\n    {\"path\": \"pkg\", \"type\": \"dir\"},\n    {\"path\": \"pkg/api\", \"type\": \"dir\"},\n    {\"path\": \"pkg/api/handler.go\", \"type\": \"file\"},\n    {\"path\": \"README.md\", \"type\": \"file\"},\n    {\"path\": \"go.mod\", \"type\": \"file\"}\n  ]\n}\n```\n\n### Markdown Format\n\nOptimized for documentation and LLM consumption. Groups files by directory with clear sections.\n\n```bash\ndirtree --format markdown\n```\n\nOutput:\n```markdown\n# Directory Structure: .\n\n## Files\n### Root Directory\n- `README.md`\n- `go.mod`\n\n### cmd/\n- `main.go`\n\n### pkg/api/\n- `handler.go`\n\n## Directories\n- `cmd/`\n- `pkg/`\n- `pkg/api/`\n\n---\n**Total:** 3 files, 3 directories\n```\n\n### LLM Mode\n\nSpecial mode optimized for AI agents with sensible defaults:\n\n```bash\ndirtree --llm\n```\n\nThis is equivalent to: `--format markdown --level 3 --max-files 200`\n\nBenefits for LLM usage:\n- Markdown format is easier for LLMs to parse\n- Depth limit (3) prevents context overflow\n- File limit (200) keeps output manageable\n- Grouped structure helps with understanding project organization\n\n## How It Works\n\n### Gitignore Handling\n\ndirtree reads `.gitignore` files at each directory level and respects all standard gitignore patterns:\n\n- **Wildcard patterns**: `*.log`, `*.tmp`\n- **Directory patterns**: `node_modules/`, `build/`\n- **Nested patterns**: `src/**/*.test.js`\n- **Negation patterns**: `!important.log`\n\nGitignore rules are inherited from parent directories, just like Git itself handles them.\n\n### Automatic Exclusions\n\nThe following are always excluded from the output:\n- `.git` directory\n\n### File Sorting\n\nFiles and directories are sorted in the following order:\n1. **Directories** (alphabetically)\n2. **Regular files** (alphabetically)\n3. **Dotfiles** (alphabetically)\n\nThis ensures consistent, readable output across different systems.\n\n### Color Output\n\ndirtree uses intelligent color coding to make output easier to scan:\n\n- **Directories**: Blue and bold\n- **Regular files**: White\n- **Dotfiles**: Gray (dim)\n- **Executable files**: Green and bold\n- **Image files** (.png, .jpg, .gif, etc.): Magenta\n- **Documentation** (.md, .txt, .pdf, etc.): Cyan\n\nColor output respects:\n- `--color` flag (`auto`, `always`, `never`)\n- `NO_COLOR` environment variable ([no-color.org](https://no-color.org/))\n- Terminal capabilities (auto-detection in `auto` mode)\n\n### Depth Limiting\n\nControl traversal depth with the `-L` or `--level` flag:\n\n```bash\ndirtree -L 2    # Only show 2 levels deep\n```\n\nThis is useful for:\n- Getting a quick overview of large projects\n- Focusing on top-level structure\n- Avoiding deeply nested directories\n\n## Use Cases\n\n- **Documentation**: Generate directory structure for README files (Markdown format) or documentation\n- **LLM Context**: Feed project structure to AI assistants with `--llm` flag\n- **Code Review**: Quickly understand project organization\n- **Project Planning**: Visualize codebase structure before making changes\n- **Onboarding**: Help new team members understand project layout\n- **Git-Aware Exploration**: See only tracked/relevant files, ignoring build artifacts\n- **CI/CD Integration**: Use JSON format for automated project analysis\n- **Build Tools**: Parse JSON output for custom tooling and scripts\n\n## Comparison with `tree` Command\n\n| Feature | dirtree | tree |\n|---------|---------|------|\n| Respects .gitignore | ✅ Yes | ❌ No |\n| Hierarchical gitignore | ✅ Yes | N/A |\n| Multiple output formats | ✅ Yes (text/json/md) | ⚠️ Limited |\n| LLM-optimized mode | ✅ Yes | ❌ No |\n| JSON output | ✅ Yes | ⚠️ Limited |\n| Markdown output | ✅ Yes | ❌ No |\n| File count limiting | ✅ Yes | ❌ No |\n| Colorized output | ✅ Yes | ✅ Yes |\n| Depth limiting | ✅ Yes (-L) | ✅ Yes (-L) |\n| Cross-platform | ✅ Yes | ⚠️ Limited |\n| Installation | Go install | OS package manager |\n| Size | ~2MB | Varies |\n| NO_COLOR support | ✅ Yes | ⚠️ Varies |\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Quick Start for Contributors\n\n```bash\n# Clone the repository\ngit clone https://github.com/datumbrain/dirtree.git\ncd dirtree\n\n# Run tests\ngo test -v ./...\n\n# Build\ngo build\n```\n\n## Troubleshooting\n\n### Binary not in PATH\n\nAfter installation, ensure your Go bin directory is in your PATH:\n\n```bash\n# Add to ~/.bashrc or ~/.zshrc\nexport PATH=$PATH:$(go env GOPATH)/bin\n```\n\n### Permission Denied Errors\n\nIf you encounter permission errors when reading directories, ensure you have read permissions for the target directory.\n\n### Gitignore Not Working\n\nMake sure your `.gitignore` file:\n- Is named exactly `.gitignore` (case-sensitive)\n- Uses proper gitignore pattern syntax\n- Is in the correct directory relative to the files you want to ignore\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Authors\n\n- [Fahad Siddiqui](https://github.com/fahadsiddiqui)\n\n## Acknowledgments\n\n- Uses [go-gitignore](https://github.com/sabhiram/go-gitignore) for gitignore pattern matching\n- Uses [fatih/color](https://github.com/fatih/color) for cross-platform colored output\n- Inspired by the Unix `tree` command with Git-awareness added\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatumbrain%2Fdirtree","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatumbrain%2Fdirtree","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatumbrain%2Fdirtree/lists"}