GitHubTree
GitHubTree is a high-performance repository visualiser.
GitHubTree allows you to explore, navigate, and generate formatted directory trees for any GitHub repository without cloning. Perfect for documentation, code reviews, and project overviews.
## ✨ Features
* **Instant Explorer:** Visualize any public repository (e.g., `facebook/react`).
* **Intelligent Navigation:** Search and filter files in real-time with parent-folder context preservation.
* **Interactive Controls:** Unified tree toggles (Compact/Expand) and collapsible folder support.
* **Visual Styles:** Choose between Classic (└──), Slashed (/src), Minimal, ASCII (+--), and **Bulleted (•)**.
* **Private Repository Access:** Securely access personal repos using a GitHub PAT (stored only in your browser).
* **Deep Linking:** Share links that persist your branch, filter, sort, and style settings.
* **High Performance:** Core engine optimized for large repositories with automated branch detection.
## CLI Tool
Generate directory trees directly in your terminal.
### Usage (No Install)
```bash
npx gh-tree user/repo
```
### Global Installation
```bash
npm install -g gh-tree
```
### Commands & Flags
```bash
gh-tree [flags]
```
**Flags:**
* `--branch`, `-b `: Specify branch (default: `main`)
* `--depth`, `-d `: Limit recursion depth
* `--ignore`, `-i `: Ignore patterns (comma-separated, e.g. `node_modules,*.log`)
* `--style `: Visual style (`classic`, `bulleted`, `minimal`, etc.)
* `--json`: Output raw JSON data instead of ASCII
* `--icons`: Show file/folder icons in output
* `--token`, `-t `: Use a specific GitHub Token
* `--save-token `: Save a token globally for future use
* `--clear-cache`: Clear local tree cache
### CLI Examples
```bash
# Basic usage
gh-tree mgks/githubtree
# Limit depth and ignore specific patterns
gh-tree facebook/react -d 2 -i "node_modules,*.log"
# Show icons and use a specific branch
gh-tree user/repo --branch develop --icons
# Output as JSON for processing
gh-tree user/repo --json > tree.json
```
## For Builders: NPM Package
Use the core engine to integrate tree generation into your own Node.js applications.
### Installation
```bash
npm install gh-tree
```
### Quick Start
```javascript
import { GitHubTree } from 'gh-tree';
const gt = new GitHubTree(process.env.GITHUB_TOKEN);
try {
const { tree } = await gt.getTree('mgks/githubtree', 'main');
const output = gt.generateAsciiTree(tree, { style: 'classic', icons: true });
console.log(output);
} catch (err) {
console.error(err);
}
```
## Local Development (Monorepo)
* `packages/core`: Core logic, API fetcher, and CLI tool.
* `packages/web`: Vite-based Web Application.
* `tools/`: SEO and static page generation scripts.
1. **Clone & Install:**
```bash
git clone https://github.com/mgks/GitHubTree.git
cd GitHubTree
npm install
```
2. **Run Development Server:** `npm run dev`
3. **Deploy Production Build**: `npm run deploy`
## Contributing
Contributions are welcome! If you have a feature request, bug report, or a pull request, please feel free to open an issue or submit a PR on [GitHub](https://github.com/mgks/GitHubTree).
1. **Fork the Repo**
2. **Create a Feature Branch** (`git checkout -b feature/amazing-feature`)
3. **Commit Changes** (`git commit -m 'Add amazing feature'`)
4. **Push to Branch** (`git push origin feature/amazing-feature`)
5. **Open a Pull Request**
## License
MIT
 